REST API Authentication¶

The Nautobot REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browseable 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.

Sign into Nautobot
On the upper right hand corner, select your username, then Profile
On the left hand side, under User Profile, select API Tokens
Select +Add a token
Leave Key blank to automatically create a token, or fill one in for yourself
Check or uncheck "Write enabled", as desired
(Optional) Set an expiration date for this token
(Optional) Add a description

Note

The creation and modification of API tokens can be restricted per user by an administrator. If you don't see an option to create an API token, ask an administrator to grant you access.

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."
}

Initial Token Provisioning¶

Added in version 1.3.0

Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. Nautobot provides a special endpoint to provision tokens using a valid username and password combination.

To provision a token via the REST API, make a POST request to the /api/users/tokens/ endpoint:

$ curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
-u "hankhill:I<3C3H8" \
https://nautobot/api/users/tokens/

Note that we are not passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled.

{
    "id": "e87e6ee9-1ab2-46c6-ad7f-3d4697c33d13",
    "url": "https://nautobot/api/users/tokens/e87e6ee9-1ab2-46c6-ad7f-3d4697c33d13/",
    "display": "3c9cb9 (hankhill)",
    "created": "2021-06-11T20:09:13.339367Z",
    "expires": null,
    "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
    "write_enabled": true,
    "description": ""
}