Accessing many modern APIs requires an authorization token to be sent with each request. Authorization tokens allow the API to validate the caller and ensure they have the permissions required to access the requested resources. Generating and using API tokens correctly is important for building secure integrations.
What is an API authorization token?
An API authorization token is a unique string value that is used to authenticate API requests. Tokens represent the identity of the API consumer and are generated using the consumer’s API credentials (typically a key and secret). The token proves the API caller is who they claim to be.
Authorization tokens are different from session IDs or cookies because they are not tied to a specific user session. The tokens remain valid until expiration, allowing stateless authentication of API requests.
Why use API authorization tokens?
There are several benefits to using authorization tokens with APIs:
- Stateless authentication – tokens allow validating API callers without managing user sessions
- Revocation – tokens can be revoked to selectively disable API access
- Expiration – tokens can expire after a set time period, requiring renewal
- Scalability – token validation puts minimal load on API servers
- Security – tokens are more secure than sending API keys in requests
Overall, tokens allow more control, security, and scalability than API key-based access alone. Modern APIs almost always use token-based access control.
How API authorization tokens work
API tokens work through cryptographic signing or encryption. When a token is generated, the API credentials used to create it are encoded in the token string. This allows the API to later decode the credentials from the token for verification.
There are two main types of encoding used for API tokens:
- Signed tokens – encode credentials in plaintext and are signed with a secret to prevent tampering
- Encrypted tokens – credentials are encrypted and can only be decrypted with a secret key
Once generated, tokens are passed along with API requests usually in an Authorization header:
Authorization: Bearer [token]
The API receives the request, decodes the token to extract credentials, verifies those credentials, and then authorizes the request if valid.
Where to get API keys and secrets
To generate API tokens, you first need to obtain API credentials (keys and secrets) for the service you want to access. These keys are obtained by registering as a developer with the API provider.
Here are some ways to get API keys:
- Create a developer account on the API provider’s website
- Subscribe to the API through a developer portal
- Contact the API provider directly about access
- Look for API keys within apps using the API (for internal APIs)
The credentials usually involve an API key (public identifier) and a secret. The secret allows generating signatures or encryption the API can validate.
Generating a signed API token
Signed tokens encode the API credentials into the token plaintext. A signature is added to verify the token’s integrity:
[header].[payload].[signature]
To create a signed token:
- Serialize credentials claims (key, secret, etc) into a JSON payload
- Base64 encode the JSON payload to create the token body
- Sign the encoded body with an HMAC signature using the API secret
- Concatenate the header, body, and signature with periods
For example, in Python:
import jwt payload = {'key': '1234', 'secret': '5678'} token = jwt.encode(payload, 'secret', algorithm='HS256')
The API verifies the signature to authenticate the token upon receipt.
Generating an encrypted API token
Encrypted tokens encode the credentials payload with encryption rather than signing:
[header].[encrypted body]
To encrypt a token:
- Serialize credentials to a JSON payload
- Encrypt the JSON body using the API’s secret key
- Concatenate header and encrypted body
For example, in Python:
import jwt payload = {'key': '1234', 'secret': '5678'} token = jwt.encode(payload, 'secret', algorithm='HS256')
The API uses its secret key to decrypt the credentials for verification.
Customizing token claims
In addition to API credentials, tokens can include other metadata:
- User identity
- Authorized scopes
- Key ownership details
- Expiration time
Adding custom fields allows tokens to carry more context for the API to authorize against. For example, scopes can specify permissions:
{ "key": "1234", "scopes": ["read","write"] }
Expiration times are also common to limit how long tokens are valid:
{ "key": "1234", "exp": 1516239022 }
Managing authorization tokens
Properly managing API tokens is important for security:
- Secure storage – store tokens securely on client devices using encryption
- Limited sharing – avoid copying tokens outside of necessary usage
- Short expiration – use short token expiration to limit damage from leaks
- One-time use – issue single-use tokens and discard after use
- Revocation – revoke compromised tokens immediately
Following these practices limits the blast radius of any leaked tokens.
Revoking authorization tokens
Issuing short-lived tokens helps reduce the need for revocation. But for long-lived tokens, revocation is important to disable compromised credentials.
To allow revocation, the API needs to:
- Store metadata on issued tokens in a database
- Check each API call against the database
- Mark revoked tokens in the database
The token database allows validating tokens on each request and denying any marked revoked. This immediately disables compromised tokens systemwide.
Refreshing expired tokens
Short token expiration improves security but can be inconvenient for users. APIs usually support refresh tokens to streamline renewal:
- User authenticates and gets initial short-lived access token
- Access token is used until expiration
- Refresh token is used to get a fresh access token
- New access token used until expiration
Refresh tokens have longer expiration so less frequent renewal is needed. Users can thus stay authenticated indefinitely.
Using authorization tokens in apps
Client apps need to properly handle API tokens:
- Tokens should only be stored in secure credential storage like a keychain
- Set expiration timers based on token expiration claims
- Refresh tokens in the background before expiration
- Check errors for unauthorized indications to retry renewal
- Never hardcode tokens in source code
Following these practices ensures a smooth user experience while maintaining security.
Conclusion
Authorization tokens allow accessing modern APIs securely. Tokens encode API credentials cryptographically so the API can validate callers are authorized. Properly generating, managing, and using tokens is essential for robust API access control.