API Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005uhwsaq&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fapi-54325410
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
API
Published: Jan 31, 2018   -   Updated: May 15, 2018

okta-doc-source

API

Use the API page to manage and create all Okta API tokens, and to add Origin URLs.

Tokens

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 token are generated with the permissions of the user that created the token. If a user’s permissions changes, then so does that of the token. Okta recommends generating API tokens from a service account with permissions that do not change.

API tokens are valid for 30 days and automatically renew every time they are used with an API request. When a token has been inactive for more than 30 days it is revoked and cannot be used again. Tokens are also only valid if the user who created the token is also active. Tokens issued by deactivated users are rejected. If the user account is reactivated, the API token is accepted with no other action required.

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 are managed by Okta.

Use the API Token page to manage all Okta API tokens. Agent tokens are usually 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 usually handled automatically when you activate or reactivate an agent. This list of tokens contains Okta token usage information for your organization.

There are five actions available to manage tokens.

Create Okta API tokens

To create your own token to authenticate with the Okta API, navigate to Security > API and click the Create Token button.

Important: The only time you can view the token is during the creation process. You might want to capture a screen shot of it for future reference. After the token is created, it is stored as a hash for your protection. Treat API tokens like passwords. Be sure to store the screenshot in a secure place.

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 at the right.

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 has not 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 is not registered in Okta. Normal agent deployments do not create suspicious tokens.

    Recommendation: Investigate suspicious tokens. Click on the token name and review the provisioning for the associated agent. If the agent is not 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. Additionally, the Suspicious Tokens category contains tokens that are associated with an agent that is not registered in Okta.

In addition to the token group, you can list a single token. 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 trash icon to the right of the token information is clickable if you can revoke the token.

  • API Tokens are always revocable.
  • Agent tokens are revocable if the agent is not 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.
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 did not create the token revokes it, the actor and target contain different information.

Trusted Origins tab

All cross-origin web requests and redirects from Okta to your organization’s websites must be explicitly whitelisted. Use the Trusted Origins tab to grant access to websites that you control and trust to access your Okta org through the Okta API. An Origin is a security-based concept that combines the URI scheme, hostname, and port number of a page.

To access the Trusted Origins page, do the following:

  1. Click Trusted Origins.
  2. Click the Add Origin button. The Add Origin screen appears.
  3. Enter the Name and Origin URL fields for the page.
  4. Choose the Origin type from the following list.
    • CORS – Cross-Origin Resource Sharing (CORS) allows JavaScript hosted on your websites to make an XMLHttpRequest to the Okta API using the Okta session cookie.
    • Redirect – Allows for browser redirection to your org's trusted websites after signing in or out.

Rate Limiting

API endpoint throttling limits have been created to protect the Okta service (in Production and Preview tenants) from load spikes or service interruptions caused by submitted requests (whether unintentional or as a Denial of Service attack). This strategy has been adopted across the industry in many SaaS applications and platforms to maintain consistent service levels for customers. Requests that hit the rate limits return a "429 Too Many Requests" HTTP status code.

Public applications are aggressively rate-limited to prevent abuse and require primary authentication to be successfully completed before releasing any metadata about a user. For more information, see Okta Authentication API.

Concurrent Rate Limits

In order to protect the service for all customers, Okta enforces concurrent rate limits. These limits are distinct from the org-wide, per minute API rate limits.

For concurrent rate limits, traffic is measured in three different areas: agent traffic, Microsoft Office 365 traffic, and all other traffic, including API requests. Counts in one area are not included in counts for the other two areas.

  • For agent traffic, Okta measured each org’s traffic and set the limit at above the highest usage in the last four weeks.
  • For Microsoft Office 365 traffic, the limit is 75 concurrent transactions per org.
  • For all other traffic including API requests, the limit is 75 concurrent transactions per org.

The first request to exceed the concurrent limit returns an HTTP 429 error, and the first error every sixty seconds is written to the log. Reporting concurrent rate limits once a minute keeps log volume manageable.

Default Rate Limits

API endpoint throttling limits have been created to protect the Okta service (in Production and Preview tenants) from load spikes or service interruptions caused by submitted requests, whether unintentional or as a Denial of Service attack. This strategy has been adopted across the industry in many SaaS applications and platforms to maintain consistent service levels for customers. Requests that hit the rate limits return a 429 Too Many Requests HTTP status code.

Public applications are aggressively rate-limited to prevent abuse and require primary authentication to be successfully completed before releasing any metadata about a user. For detailed information about Okta API rate limits, including working with headers that report the limit in each API response, see https://developer.okta.com/docs/api/getting_started/design_principles#rate-limiting

Other default rate limits are listed by endpoint in the following table. Okta may raise or lower the limits without notice in the process of maintaining the service.

Rate Limited URI

Requests per minute

/app/{app}/{key}/sso/saml

750

/app/office365/{key}/sso/wsfed/active

2,000

/app/office365/{key}/sso/wsfed/passive

250

/app/template_saml_2_0/{key}/sso/saml

2,500

/login/do-login

200

/login/login.htm

850

/login/sso_iwa_auth

500

/api/plugin/{protocol version}/form-cred/{app user IDs}/{form site option}650
/api/plugin/{protocol version}/sites150
/bc/fileStoreRecord500
/bc/globalFileStoreRecord500

End-User Rate Limit

Okta limits the number of requests from the Okta user interface to 40 requests per user per 10 seconds per endpoint. This rate limit protects users from each other, and from other API requests in the system.

If a user is able to exceed this limit, they are locked out until the rate limit passes, and a message is written to the user interface and the System Log.

Requesting Exceptions

While endpoint throttling is enforced uniformly for all Okta customers, there are occasionally scenarios where a customer request for a temporary rate limit increase can be accommodated. An example would be an initial deployment scenario where a very large number of users and groups are being imported to Okta. In such a scenario, the customer can seek to make arrangements for a temporary exception.

Requests must be received 10 business days prior to the time frame during which an increase is required. To request an exception, open a case with Okta Support and provide the following details:

  1. Org Name
  2. Endpoints and Rates
    • Which URI's need to have their limits increased
    • How much of an increase is required?
  3. Start date and time
  4. End date and time
  5. Business Justification
    • Please provide details on your organizations requirements that drive the request.

Okta reserves the right to rate limit other functionality to prevent abuse, spam, denial-of-service attacks, or other security issues. Where possible Okta will offer a descriptive error code.

Post a Comment