diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 8e38c4de9..e8e6ddc96 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -2,18 +2,7 @@ The NetBox API employs token-based authentication. For convenience, cookie authentication can also be used when navigating the browsable API. -## Tokens - -A token is a unique identifier that identifies a user to the API. Each user in NetBox may have one or more tokens which he or she can use to authenticate to the API. To create a token, navigate to the API tokens page at `/user/api-tokens/`. - -!!! 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, NetBox 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 for all operations available via the API. 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 NetBox. +{!docs/models/users/token.md!} ## Authenticating to the API diff --git a/docs/models/users/token.md b/docs/models/users/token.md new file mode 100644 index 000000000..bbeb2284b --- /dev/null +++ b/docs/models/users/token.md @@ -0,0 +1,12 @@ +## Tokens + +A token is a unique identifier that identifies a user to the API. Each user in NetBox may have one or more tokens which he or she can use to authenticate to the API. To create a token, navigate to the API tokens page at `/user/api-tokens/`. + +!!! 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, NetBox 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 for all operations available via the API. 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 NetBox. diff --git a/docs/release-notes/version-2.8.md b/docs/release-notes/version-2.8.md index ff6ba4e50..aea825ce3 100644 --- a/docs/release-notes/version-2.8.md +++ b/docs/release-notes/version-2.8.md @@ -6,6 +6,7 @@ v2.8.4 (FUTURE) * [#4598](https://github.com/netbox-community/netbox/issues/4598) - Display error message when invalid cable length is specified * [#4604](https://github.com/netbox-community/netbox/issues/4604) - Multi-position rear ports may only be connected to other rear ports +* [#4607](https://github.com/netbox-community/netbox/issues/4607) - Missing Contextual help for API Tokens ---