Manage Okta API tokens

Use the Tokens tab on the API page to manage and create Okta API tokens and configure restrictions on where they can connect from.

API tokens are used to authenticate requests to the Okta API. An API token is issued for a specific user. All requests made 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, generate API tokens using a service account that won't be deactivated and that has 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, Okta manages them.

Agent tokens appear 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, deactivate, or reactivate an agent.

For more information on Okta APIs, see the Okta Developer site.

Create Okta API tokens

You can create Okta API tokens and configure restrictions on where they can connect from.

  1. In the Admin Console, go to SecurityAPI.
  2. Click the Tokens tab.
  3. Click Create token.
  4. In the What do you want your token to be named? field, enter a token name.
  5. From the API calls made with this token must originate from dropdown list, select an option to specify where you allow connections to come from:
    • Any IP: Allow connections from any IP address or network zone.
    • In any network zone defined in Okta: Allow connections if they come from any network zone defined in your Okta org.
    • In any of the following zones: Allow connections if they come from network zones that you specify. Start entering text that matches the name of the network zone you want to select. Okta presents results that match what you entered. Click a name to select it. Repeat this step to add more network zones.
    • Not in any network zone defined in Okta: Allow connections if they don't come from any network zone defined in your Okta org.
    • Not in any of the following zones: Allow connections if they don't come from network zones that you specify. Start entering text that matches the name of the network zone you want to select. Okta presents results that match what you entered. Click a name to select it. Repeat this step to add more network zones.
    • You can only use IP-based zones with SSWS tokens. Ensure that you add them to the Gateway IP addresses field on the Add IP Zone page. See IP zone evaluation.
    • You can't use blocklist zones with SSWS tokens. See Create a dynamic zone.
  6. Click Create token.

  7. The Token created successfully! message and the token value appear.

  8. Click Copy to clipboard (Copy token) and paste the token in a secure location, such as a password manager. 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. Okta recommends that you treat API tokens like passwords.

Set token rate limits (optional)

When you create API tokens 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.

  1. In the Admin Console, go to SecurityAPI.
  2. Click the Tokens tab.
  3. Click the name of the token that you want to edit.
  4. In the Token rate limits section, click Edit.

  5. Adjust the slider to the desired percentage.

  6. Click Save.

View tokens

All tokens appear when you open the Tokens tab of the API page. The token name, ID, role, status, type, and last-used date appear for each token.

To view more information about a token, click the name of the token.

To sort the display, click Sort by and select a sort type.

To search for a token, click in the search field, enter the token name, and then press Enter.

To view information about the user who created the token, click the user's name under the Role column.

The following color codes indicate 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 more than seven days remain 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. Okta recommends that you 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 deactivated it without reactivating it, you can revoke and delete the token from this page.

To view tokens by type, select a token type in the list on the left to limit the display to that token type. The suspicious tokens category contains tokens that are associated with an agent that isn't registered in Okta. This list is dynamic and changes as the token count and types change.

Revoke a token

There are two ways to revoke a token:

  • On the API page Tokens tab, click the Revoke token icon (the trash icon) under the Actions column for the token you want to revoke.
  • On the API page Tokens tab, click the name of the token you want to revoke. On the token's page, click Revoke token.

The Revoke token icon or button isn't always active:

  • Agent tokens are revocable if the agent isn't active. If the agent is active, 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.

Edit the network zones that API calls can come from

You can add or change restrictions to where API calls can come from after you've created a token.

  1. In the Admin Console, go to SecurityAPI.
  2. Click the Tokens tab.
  3. Click the name of the token that you want to edit.
  4. In the Security section, click Edit.
  5. From the Token can be used from dropdown, select an option to specify where you allow connections to come from:
    • Any IP: Allow connections from any IP address or network zone.
    • In any network zone defined in Okta: Allow connections if they come from any network zone defined in your Okta org.
    • In any of the following zones: Allow connections if they come from network zones that you specify. Enter text that matches the name of the network zone you want to select. Okta presents results that match what you enter. Select a name. Repeat this step to add more network zones.
    • Not in any network zone defined in Okta: Allow connections if they don't come from any network zone defined in your Okta org.
    • Not in any of the following zones: Allow connections if they don't come from network zones that you specify. Enter text that matches the name of the network zone you want to select. Okta presents results that match what you enter. Select a name. Repeat this step to add more network zones.
    • You can only use IP-based zones with SSWS tokens. Ensure that you add them to the Gateway IP addresses field on the Add IP Zone page. See IP zone evaluation.
    • You can't use blocklist zones with SSWS tokens. See Create a dynamic zone.

  6. Click Save.

View token history

You can view information about when the token was created, when it was last used, and when it expires.

  1. In the Admin Console, go to SecurityAPI.
  2. Click the Tokens tab.
  3. Click the name of the token that you want to view the history for.
  4. Review the information in the History section.

Track tokens in the System Log

The System Log contains 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 the creator of a token revokes 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.

Related topics

API access management

Configure Trusted Origins