API token management
Use the API page to manage and create all Okta API tokens and to add origin URLs. For additional information on Okta APIs, see the Okta Developer Site.
API tokens are used to authenticate requests to the Okta API just like HTTP cookies authenticate requests to the Okta Application with your browser. An API token is issued for a specific user and all requests with the token act on behalf of the user. API tokens are secrets and should be treated like passwords.
API tokens are generated with the permissions of the user that created the token. If a user’s permissions change, then so do the token’s. Super admins, org admins, group admins, group membership admins, and read-only admins may create tokens.
Tokens are valid only if the user who created them is active. Tokens issued by deactivated users are rejected. To avoid service interruptions, Okta recommends generating API tokens using a service account that won’t be deactivated and with super admin permissions that won’t change.
API tokens are valid for 30 days and automatically renew every time they're used with an API request. When a token has been inactive for more than 30 days, it's revoked and can't be used again.
Okta Agents are also issued API tokens during installation, which they use to access your Okta organization. While these tokens are similar to the standard API token, they're managed by Okta.
Use the API token page to manage all Okta API tokens. Agent tokens are managed when you activate, deactivate, or reactivate an agent.
Agent tokens are displayed on this page for your review, and to highlight any security issues that might arise with them. Most agents use a token. The token setup is handled automatically when you activate or reactivate an agent. This list of tokens contains Okta token usage information for your organization.
Create Okta API tokens
To create your own token to authenticate with Okta APIs:
-
In the Admin Console, go to Security > API.
-
Click Tokens and then Create Token.
- Enter a token Name and then click Create Token.
- Optional. Click Copy to clipboard (
).The only time you can view and copy the token is during the creation process. After the token is created, it's stored as a hash for your protection. Treat API tokens like passwords. You might want to capture an image of it for future reference, but be sure to store it in a secure place.
Set token rate limits (optional)
When API tokens are created using the Admin Console, rate limits for token interactions are set automatically to 50 percent of each API maximum limit. See API rate limits. You can adjust this percentage for each token.
- On the API Tokens page, click Edit Token (
) for the token you want. - In the Token rate limits section, click Edit.
-
Adjust the slider to the desired percentage.
-
Click Save.
View all tokens
All tokens are displayed when you open the API tokens page. The token status, type, name, use, and creation, expiration, and last used dates for all agent and API tokens are shown. To sort the display, choose a sort from the Sort by dropdown menu.
The following color codes are used to show the token status.
- Green – the token has been used within the last three days.
- Gray – the token hasn't been used in the last three days, and today is at least seven days before its expiration date.
- Red – the token is within seven days of expiring.
- Yellow – the token is suspicious.
A suspicious token is associated with an agent that isn't registered in Okta. Normal agent deployments don't create suspicious tokens.
Recommendation: Investigate suspicious tokens. Click the token name and review the provisioning for the associated agent. If the agent isn't registered in Okta or if you have deactivated it without reactivating it, you can revoke and delete the token from this page.
View by token type
Select any token type from the list on the left to limit the display to that token type. Most of the categories are types of tokens. Also, the suspicious tokens category contains tokens that are associated with an agent that isn't registered in Okta.
To find a single token, enter the token value and then select Find Token.
The number of tokens for a particular type is always shown. This list is dynamic and changes as the token count and type changes.
Revoke tokens
To revoke a token, click the trash icon at the right of the token information. The icon isn't always active:
- Agent tokens are revocable if the agent isn't active; otherwise, you must deactivate the agent before revoking the token. Some agents such as the Okta AD Agent automatically revoke their tokens for you when you deactivate the agent.
- API tokens are always revocable.
Track in the System Log
The System Logs contain information about API token creation and revocation. The message associated with these operations is either API token created or API token revoked. In the System Log v1, which is only accessible through the Okta API, the category for these events is token lifecycle.
If a token is revoked by the same user who created it, the actor and target contain the same information. If an admin who didn't create the token revokes it, the actor and target contain different information.