REST API Authentication¶

The Nautobot REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API.

Tokens¶

A token is a unique identifier mapped to a Nautobot user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile.

Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, Nautobot allows you to specify a key in case you need to restore a previously deleted token to operation.

By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only.

Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to Nautobot.

Authenticating to the API¶

An authentication token is attached to a request by setting the Authorization header to the string Token followed by a space and the user's token:

$ curl -H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
http://nautobot/api/dcim/sites/
{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [...]
}

A token is not required for read-only operations which have been exempted from permissions enforcement (using the EXEMPT_VIEW_PERMISSIONS configuration parameter). However, if a token is required but not present in a request, the API will return a 403 (Forbidden) response:

$ curl http://nautobot/api/dcim/sites/
{
    "detail": "Authentication credentials were not provided."
}