API Access Management Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
API Access Management
Published: Jan 31, 2018   -   Updated: Jun 22, 2018




API Access Management

This is an Early Access feature. To enable it, please contact Okta Support.

API Access Management allows you to build custom authorization servers in Okta which can be used to protect your own API endpoints.

What is an authorization server?

An authorization server defines your security boundary, for example “staging” or “production.” Within each authorization server you can define your own OAuth scopes, claims, and access policies. This allows your apps and your APIs to anchor to a central authorization point and leverage the rich identity features of Okta, such as Universal Directory for transforming attributes, adaptive MFA for end-users, analytics, and system log, and extend it out to the API economy.

At its core, an authorization server is simply an OAuth 2.0 token minting engine. Each authorization server has a unique issuer URI and its own signing key for tokens in order to keep proper boundary between security domains. The authorization server also acts as an OpenID Connect Provider, which means you can request ID tokens in addition to access tokens from the authorization server endpoints.

How do I choose an authorization service?

How do you know if you need to use Okta’s authorization server instead of the authorization service that is built in to your Okta app?

  • You need to protect non-Okta resources.
  • You need different authorization policies depending on whether the person is an employee, partner, or end user, or other similar specializations.

Note: If your employees, partners, and users can all use the same authentication policies for single sign-on, try Okta’s built in authorization service.

How do I set up an authorization server?

To manage authorization between clients and Okta,

  • Identify the scopes and claims in your client app and register it with Okta.
  • Create one or more authorization servers and define the scopes and claims to match those expected by your app.

It doesn’t matter which task you do first, but the client app must recognize the scope names and be expecting the claims as defined in the authorization server.

To create and configure an authorization server, follow these steps:

Create the Authorization Server
  1. From the dashboard, select Security > API, and select the Authorization Servers tab. Then, click Add Authorization Server and supply the following editable information. Issuer, Metadata URI, and Last Rotation are not editable.
    • Name
    • Audience – URI for the OAuth resource that consumes the Access Tokens. This value is used as the default audience for Access Tokens.
    • Description
    • Signing Key Rotation – Automatic or manual. (Manual should only be used for clients that are unable to poll the authorization server to update their list of signing keys automatically. If you use manual, Okta recommends that you rotate keys every three months.)

When complete, your authorization server Settings tab displays the information that you provided and allows you to edit it.


Create Scopes

Scopes represent high-level operations that can be performed on your API endpoints. These are coded into applications, which then ask for them from the authorization server, and the access policy decides which ones to grant and which ones to deny.

If you need scopes in addition to the reserved scopes provided, create them now.

  1. Choose the name of the authorization server to display it, and then select Scopes.

  2. Choose Scopes > Add Scope,
  3. Enter a name and description.
  4. Select Default scope if you want to allow Okta to grant authorization requests to apps that do not specify scopes on an authorization request. If the client omits the scope parameter in an authorization request, Okta returns all default scopes in the Access Token that are permitted by the access policy rule.

  5. Click Create to save the scope.


These scopes are referenced by the Claims dialog.

Note: If you create an app that uses the User Consent for OAuth 2.0 and OpenID Connect Flows feature, set the User Consent to Yes for the scope, as shown below.


Create Claims

Tokens contain claims that are statements about the subject or another subject, for example name, role, or email address.

ID Token claims are dynamic. By default, the Authorization Server does not include them in the ID Token when requested with an Access Token or authorization code. To use this default, select When Requested for Include in token type.

To force the Authorization server to always put an ID Token claim into the ID Token, select Always for Include in token type.

Note: If the claim is not included, the client must use an Access Token to get the claims from the UserInfo endpoint.


Create ID Token claims for OpenID Connect, or Access Tokens for OAuth 2.0:

  1. Choose the name of the authorization server to display it, and choose Claims. Okta provides a default subject claim. You can edit the mapping, or create your own claims.
  2. Choose Add Claim and provide the requested information.

    • Name
    • Include in token type: Choose the token type in the first dropdown box. Select Access Token (Oauth 2.0) or ID Token (OpenID Connect). . In the second dropdown box, choose Always or Userinfo/id_token request.
    • Value type: Choose whether you’ll define the claim by a group filter or by an Expression written in Okta Expression Language.
      • Mapping: This option displays if you chose Expression in the previous field. Add the mapping here using Okta’s Expression Language, for example appuser.username. Be sure to check that your expression returns the results expected–the expression isn’t validated here.
      • Filter: This option displays if you chose Groups in the previous field. Use it to add a group filter. If you leave it blank, all users are specified for this claim.
    • Disable claim: Check this option if you want to temporarily disable the claim for testing or debugging.
    • Include in: Specify whether the claim is valid for any scope, or select the scopes for which it is valid.

While in the Claims list, you can:

  • Sort claims by type.
  • Delete claims you’ve created, or disable claims for testing or debugging purposes.


Create Access Policies
  1. Choose the name of an authorization server.
  2. Choose Access Policies > Add New Access Policy
  3. Provide the requested information:
    • Name
    • Description
    • Assign to All clients, or select The following clients: and enter the name of the clients covered by this access policy.

While in the Access Policy list, you can:

  • Set access policies to be active or deactivate them for testing or debugging purposes.
  • Reorder policies to change the order policies are evaluated.
  • API_Access_4_652x215

Polices are evaluated in priority order, as are the rules in a policy. The first policy and rule that matches the client request is applied and no further rule or policy processing occurs.

Create Rules for Each Access Policy

Rules control the mapping of client, user, and custom scope. For example, you can specify a rule for an access policy so that if the user is assigned to a client, then custom scope Scope1 is valid.

  1. Choose the name of an authorization server, and select Access Policies.
  2. Choose the name of an access policy, and select Add Rule


  3. Enter the requested information:
    • Rule Name
    • IF Grant type is – Select whether the client is acting on behalf of itself or on behalf of a user. You can select both. If the client is acting on behalf of a user, select any or all of the methods.
    • AND User is – This option only appears if you checked Client acting on behalf of a user above. You can choose Any user assigned to the app, or define the users further.
    • AND Scopes requested – Choose the scopes (any scopes, or a list that you specify) that are granted if the user meets any of the conditions.
    • THEN Access token lifetime is – Choose the length of time before an access token expires.
    • AND Refresh token lifetime is – Choose the length of time before a refresh token expires.
  4. Choose Create Rule to save the rule.


While in the Rules list for an access policy, you can:

  • Set a rule to be inactive for testing or debugging.
  • Reorder rules, except for the default rule in the default policy. Rules are evaluated in priority order, so the first rule in the first policy that matches the client request is applied and no further processing occurs.

    Note: Service applications (client credentials flow) have no user. If you use this flow, make sure you have at least one rule that specifies the condition No user.

  • Selecting the information icon or clicking on the rule name displays the users and groups the rule applies to, as well as the scopes that are granted to those users and groups, as shown below.


Test Your Authorization Server Configuration

For each combination of authorization serve, scopes and claims, client, and user, issue an API call and check that the contents of the ID Token or Access Token are as expected.

Token preview for OpenID Connect ID or OAuth 2.0 access tokens

Configuring an application or integration to use OpenID Connect ID tokens or Oauth 2.0 access tokens can take a lot of trial-and-error. Okta has made it easier to choose configuration settings and see the resulting tokens in the Token Preview tab of the Authorization Server page, as shown below.

Add values on the left side to see how they would affect the token on the right. All the fields are selection boxes except User. For User, type in the first few letters to see a choice of user names.

You can try out different combinations of values, and see the resulting tokens (or error messages). Once you've got the right combination, it's easy to configure your authorization server and other components.


Delete an Authorization Server

To delete an authorization server, click the Actions button to the right of the authorization server name, and the click Delete.

Searching for Authorization Servers

Use the search field to search on the exact name of the authorization server or Resource URI.

AS_with Search Field_730x436

Rotating Keys Manually

You can set an authorization server to manually rotate keys. Keys are rotated automatically by default.

Important: Automatic key rotation is more secure than manual key rotation. Use manual key rotation only if you can't use automatic key rotation

To change an authorization server configuration:

  1. Log into the Okta org.
  2. From the Admin Dashboard, go to Security > API.
  3. Open an authorization server for editing.
  4. Change the value of Signing Key Rotation to Manual and save.
  5. In the authorization server Settings tab, click the Rotate Signing Keys button to rotate the keys manually. This button doesn’t display when Signing Key Rotation is set to Automatic.