Authorization Servers API

Authorization Servers generate OAuth 2.0 and OpenID Connect tokens, including access tokens and ID tokens. The Okta Management API gives you the ability to configure and manage Authorization Servers and the security policies that are attached to them. The following configuration operations can be found on this page:

Authorization Server operations
Policy operations
Scope operations
Claim operations
Key Store operations

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

Get started

Explore the Authorization Servers API: (opens new window)

This page also has information about the OAuth 2.0 Objects related to these operations.

Authorization Server operations

Use the following operations to manage Custom Authorization Servers:

Create
List
Get
Update
Delete
Activate
Deactivate

Work with the Default Authorization Server

Okta provides a pre-configured Custom Authorization Server with the name default. This Default Authorization Server includes a basic access policy and rule, which you can edit to control access. It allows you to specify default instead of the authorizationServerId in requests to it:

https://${yourOktaDomain}/api/v1/authorizationServers/default vs
https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId} for other Custom Authorization Servers

Authorization Server object

When you use these API endpoints to create or modify an Authorization Server resource, the response looks like:

{
  "id": "{authorizationServerId}",
  "name": "Sample Authorization Server",
  "description": "Authorization Server Description",
  "audiences": [
    "https://api.resource.com"
  ],
  "issuer": "https://{yourOktaDomain}/oauth2/{authorizationServerId}",
  "issuerMode": "ORG_URL",
  "status": "ACTIVE",
  "created": "2017-05-17T22:25:57.000Z",
  "lastUpdated": "2017-05-17T22:25:57.000Z",
  "credentials": {
    "signing": {
      "rotationMode": "AUTO",
      "lastRotated": "2017-05-17T22:25:57.000Z",
      "nextRotation": "2017-08-15T22:25:57.000Z",
      "kid": "WYQxoK4XAwGFn5Zw5AzLxFvqEKLP79BbsKmWeuc5TB4"
    }
  },
  "_links": {
    "scopes": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/scopes",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "claims": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/claims",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "policies": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/policies",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}",
      "hints": {
        "allow": [
          "GET",
          "DELETE",
          "PUT"
        ]
      }
    },
    "metadata": [
      {
        "name": "oauth-authorization-server",
        "href": "https://{yourOktaDomain}/oauth2/{authorizationServerId}/.well-known/oauth-authorization-server",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      {
        "name": "openid-configuration",
        "href": "https://{yourOktaDomain}/oauth2/{authorizationServerId}/.well-known/openid-configuration",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      }
    ],
    "rotateKey": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/lifecycle/keyRotate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Authorization Server properties

Property	Description	Type	Required for create or update
_links	List of discoverable resources related to a Custom Authorization Server	Links	False
audiences	The recipients that the tokens are intended for. This becomes the `aud` claim in an access token. Currently, Okta supports only one audience.	Array	True
credentials	Keys and settings used to sign tokens.	Credentials object	False
description	The description of a Custom Authorization Server	String	True
default	Indicates whether the custom authorization server is the default custom authorization server	Boolean	False
issuer	The complete URL for a Custom Authorization Server. This becomes the `iss` claim in an access token.	String	False
issuerMode	Indicates which value is specified in the issuer of the tokens that a Custom Authorization Server returns: the original Okta org domain URL or a custom domain URL.	String	False
name	The name of a Custom Authorization Server	String	True
status	Indicates whether a Custom Authorization Server is `ACTIVE` or `INACTIVE`.	Enum	False

Property details

issuerMode is visible if you have a custom URL domain configured or the Dynamic Issuer Mode feature enabled. If you have a custom URL domain configured, you can set a custom domain URL in a Custom Authorization Server, and this property is returned in the appropriate responses.

If set to ORG_URL, then in responses, issuer is the Okta org's original domain URL: https://${yourOktaDomain}.
If set to CUSTOM_URL, then in responses, issuer is the custom domain URL configured in the administration user interface.
If set to DYNAMIC, then in responses, issuer is the custom domain URL if the OAuth 2.0 request was sent to the custom domain or is the Okta org's domain URL if the OAuth 2.0 request was sent to the original Okta org domain. To enable the Dynamic Issuer Mode feature, contact Support (opens new window).

After you configure a custom URL domain, all new Custom Authorization Servers use CUSTOM_URL by default. If the Dynamic Issuer Mode feature is enabled, then all new Custom Authorization Servers use DYNAMIC by default. All existing Custom Authorization Servers continue to use the original value until changed using the Admin Console or the API, so that existing integrations with the client and resource server continue to work after the feature is enabled.

Create Authorization Server

POST /api/v1/authorizationServers

Creates a new Custom Authorization Server

Request parameters

Authorization Server properties

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "Sample Authorization Server",
  "description": "Sample Authorization Server description",
  "audiences": [
    "api://default"
  ]
}' "https://${yourOktaDomain}/api/v1/authorizationServers"

Response example

The Custom Authorization Server that you just created

List Authorization Servers

GET /api/v1/authorizationServers

Lists all Custom Authorization Servers in this Okta organization

Request parameters

Parameter	Description	Param Type	DataType	Required	Default
q	Searches the `name` and `audiences` of Authorization Servers for matching values	Query	String	FALSE
limit	Specifies the number of Authorization Server results on a page	Query	Number	FALSE	200
after	Specifies the pagination cursor for the next page of Authorization Servers	Query	String	FALSE

Parameter details

The after cursor should be treated as an opaque value and obtained through the next link relationship. See Pagination.
limit can be no larger than 200.

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers"

Response example

The Custom Authorization Servers in this Okta organization

Get Authorization Server

GET /api/v1/authorizationServers/${authorizationServerId}

Returns the Custom Authorization Server identified by authorizationServerId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	Custom Authorization Server ID. You can find the ID in the Okta user interface.	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}"

Response example

The Custom Authorization Server that you requested by ${authorizationServerId}

Update Authorization Server

PUT /api/v1/authorizationServers/${authorizationServerId}

Updates the Authorization Server identified by authorizationServerId

Note: Switching between rotation modes won't change the active signing Key.

Request parameters

Parameter	Description	Type	Required
audiences	The list of audiences that this Custom Authorization Server can issue tokens to. Currently, Okta supports only one audience.	Array	TRUE
credentials	The credentials signing object with the `rotationMode` of the Authorization Server	Authorization server credentials object	FALSE
description	The description of the Authorization Server	String	FALSE
name	The name of the Authorization Server	String	TRUE

Request example

curl -X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "New Authorization Server",
  "description": "Authorization Server New Description",
  "audiences": [
    "api://default"
  ]
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}"

Response example

The Custom Authorization Server that you updated

Delete Authorization Server

DELETE /api/v1/authorizationServers/${authorizationServerId}

Deletes the Custom Authorization Server identified by authorizationServerId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	The ID of a Custom Authorization Server to delete	String	TRUE

Request example

curl -X DELETE \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}"

Response example

HTTP/1.1 204 No Content

Activate Authorization Server

POST /api/v1/authorizationServers/${authorizationServerId}/lifecycle/activate

Makes a Custom Authorization Server for use by clients

Request parameters

Parameter	Description	Type	Required
authorizationServerId	The ID of a Custom Authorization Server to activate	String	TRUE

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/lifecycle/activate"

Response example

HTTP/1.1 204 No Content

Deactivate Authorization Server

POST /api/v1/authorizationServers/${authorizationServerId}/lifecycle/deactivate

Makes a Custom Authorization Server unavailable to clients. An inactive Custom Authorization Server can be returned to ACTIVE status by activating it again.

Request parameters

Parameter	Description	Type	Required
authorizationServerId	The ID of a Custom Authorization Server to deactivate	String	TRUE

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/lifecycle/deactivate"

Response example

HTTP/1.1 204 No Content

Policy object

When you use these API endpoints to create or modify a Policy resource, the response looks like:

{
    "type": "OAUTH_AUTHORIZATION_POLICY",
    "id": "00palyaappA22DPkj0h7",
    "status": "ACTIVE",
    "name": "Vendor2 Policy",
    "description": "Vendor2 policy description",
    "priority": 1,
    "system": false,
    "conditions": {
      "clients": {
        "include": [
          "ALL_CLIENTS"
        ]
      }
    },
    "created": "2017-05-26T19:43:53.000Z",
    "lastUpdated": "2017-06-07T15:28:17.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/policies/00palyaappA22DPkj0h7",
        "hints": {
          "allow": [
            "GET",
            "PUT",
            "DELETE"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/policies/{policyId}/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      },
      "rules": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/policies/{policyId}/rules",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      }
    }
  }

Policy properties

Property	Description	Type	Required for create or update
_links	List of discoverable resources related to the Policy	Links	System
conditions	Specifies the clients that the Policy applies to	Condition object	False
created	Timestamp when the Policy was created	DateTime	System
description	Description of the Policy	String	True
id	ID of the Policy	String	True except for create
lastUpdated	Timestamp when the Policy was last updated	DateTime	System
name	Name of the Policy	String	True
priority	Specifies the order in which this Policy is evaluated in relation to the other Policies in a Custom Authorization Server	Integer	True
status	Specifies whether requests have access to this Policy. Valid values: `ACTIVE` or `INACTIVE`	Enum	True
system	Specifies whether Okta created this Policy (`true`) or not (`false`)	Boolean	True
type	Indicates that the Policy is an authorization server Policy (`OAUTH_AUTHORIZATION_POLICY`)	String	False

Get all Policies

GET /api/v1/authorizationServers/${authorizationServerId}/policies

Returns all the Policies for the specified Custom Authorization Server

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies"

Response example

Returns the Policies defined in the specified Custom Authorization Server

Get a Policy

GET /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}

Returns a Policy by ID defined in the specified Custom Authorization Server

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}"

Response example

Returns the Policy that you requested

Create a Policy

POST /api/v1/authorizationServers/${authorizationServerId}/policies

Create a Policy for a Custom Authorization Server

Request parameters

Policy object

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "OAUTH_AUTHORIZATION_POLICY",
  "status": "ACTIVE",
  "name": "Default Policy",
  "description": "Default policy description",
  "priority": 1,
  "conditions": {
    "clients": {
      "include": [
        "ALL_CLIENTS"
      ]
    }
  }
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies"

Response example

Returns the Policy that you created

Update a Policy

PUT /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}

Change the configuration of a Policy specified by the policyId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "OAUTH_AUTHORIZATION_POLICY",
  "id": "00p5m9xrrBffPd9ah0g4",
  "status": "ACTIVE",
  "name": "default",
  "description": "default policy",
  "priority": 1,
  "system": false,
  "conditions": {
    "clients": {
      "include": [
        "ALL_CLIENTS"
      ]
    }
  }
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}"

Response example

Returns the Policy that you updated

Delete a Policy

DELETE /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}

Delete a Policy specified by the policyId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}"

Response example

HTTP/1.1 204 No Content

Activate a Policy

POST /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/lifecycle/activate

Activate a Policy specified by the policyId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/lifecycle/activate"

Response example

HTTP/1.1 204 No Content

Deactivate a Policy

POST /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/lifecycle/deactivate

Activate a Policy specified by the policyId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/lifecycle/deactivate"

Response example

HTTP/1.1 204 No Content

Policy Rule operations

Policy Rule Object
Get all Policy Rules
Get a Policy Rule
Create a Policy Rule
Update a Policy Rule
Delete a Policy Rule
Activate a Policy Rule
Deactivate a Policy Rule

Policy Rule Object

When you use these API endpoints to create or modify a Policy Rule resource, the response looks like: Policy Rule Object

Get all Policy Rules

GET /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules

Returns all the Policy Rules for the specified Custom Authorization Server and Policy

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules"

Response example

Returns a list of Policy Rules that are defined in the specified Custom Authorization Server and Policy

Get a Policy Rule

GET /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}

Returns a Policy Rule by ID that is defined in the specified Custom Authorization Server and Policy

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True
ruleId	ID of a Rule	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}"

Response example

Returns the Policy Rule that you requested

Create a Policy Rule

POST /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules

Create a Policy Rule for the specified Custom Authorization Server and Policy

Request parameters

Policy Rule Object

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "type": "RESOURCE_ACCESS",
    "name": "Default Policy Rule",
    "priority": 1,
    "conditions": {
      "people": {
        "groups": {
          "include": [
            "EVERYONE"
          ]
        }
      },
      "grantTypes": {
        "include": [
          "implicit",
          "client_credentials",
          "authorization_code",
          "password"
        ]
      },
      "scopes": {
        "include": [
          "*"
        ]
      }
    },
    "actions": {
      "token": {
        "accessTokenLifetimeMinutes": 60,
        "refreshTokenLifetimeMinutes": 0,
        "refreshTokenWindowMinutes": 10080
      }
    }
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules"

Response example

Returns the Policy Rule that you created

Update a Policy Rule

PUT /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}

Change the configuration of the Policy Rule defined in the specified Custom Authorization Server and Policy

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True
ruleId	ID of a Rule	String	True

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "type": "RESOURCE_ACCESS",
    "status": "ACTIVE",
    "name": "Default Policy Rule",
    "priority": 1,
    "conditions": {
      "people": {
        "groups": {
          "include": [
            "EVERYONE"
          ]
        }
      },
      "grantTypes": {
        "include": [
          "implicit",
          "client_credentials",
          "authorization_code",
          "password"
        ]
      },
      "scopes": {
        "include": [
            "openid",
            "email",
            "address"
        ]
      }
    },
    "actions": {
      "token": {
        "accessTokenLifetimeMinutes": 60,
        "refreshTokenLifetimeMinutes": 0,
        "refreshTokenWindowMinutes": 10080
      }
    }
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${policyId}"

Response example

Returns the Policy Rule that you updated

Delete a Policy Rule

DELETE /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}

Delete a Policy Rule defined in the specified Custom Authorization Server and Policy

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True
ruleId	ID of a Rule	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}"

Response example

HTTP/1.1 204 No Content

Activate a Policy Rule

POST /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}/lifecycle/activate

Activate a Policy Rule specified by the policyId and ruleId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True
ruleId	ID of a Rule	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}/lifecycle/activate"

Response example

HTTP/1.1 204 No Content

Deactivate a Policy Rule

POST /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}/lifecycle/deactivate

Activate a Policy Rule specified by the policyId and ruleId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
policyId	ID of a Policy	String	True
ruleId	ID of a Rule	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/rules/${ruleId}/lifecycle/deactivate"

Response example

HTTP/1.1 204 No Content

Scope operations

Get all scopes
Get a Scope
Create a Scope
Update a Scope
Delete a Scope

Scope object

When you use these API endpoints to create or modify a Scope resource, the response looks like:

[
  {
    "id": "{scopeId}",
    "name": "car:drive",
    "description": "Drive car",
    "system": false,
    "default": false,
    "displayName": "Saml Jackson",
    "consent": "REQUIRED",
    "optional": false,
    "metadataPublish": "NO_CLIENTS"
  }
]

Scope properties

Property	Description	Type	Default	Required for create or update
consent	Indicates whether a consent dialog is needed for the Scope. Valid values: `REQUIRED`, `IMPLICIT`, `FLEXIBLE`	Enum	`IMPLICIT`	True for update
optional	Indicates whether the Scope is optional. When set to `true`, the user can skip consent for the scope.	Boolean	False	False
default	Whether the Scope is a default Scope	Boolean		False
description	Description of the Scope	String		False
displayName	Name of the end user displayed in a consent dialog box	String		False
id	ID of the Scope	String		False
metadataPublish	Whether the Scope should be included in the metadata. Valid values: `NO_CLIENTS`, `ALL_CLIENTS`	Enum	`NO_CLIENTS`	True except for create
name	Name of the Scope	String		True
system	Whether Okta created the Scope	Boolean		False

A consent dialog box appears depending on the values of three elements:

prompt - a query parameter that is used in requests to /authorize
consent_method - An application property that allows you to determine whether a client is fully trusted (for example: a first-party application) or requires consent (for example: a third-party application).
consent - A Scope property, listed in the previous table, that allows you to enable or disable user consent for an individual scope.

`prompt` Value	`consent_method`	`consent`	Result
`CONSENT`	`TRUSTED` or `REQUIRED`	`REQUIRED`	Prompted
`CONSENT`	`TRUSTED` or `REQUIRED`	`FLEXIBLE`	Prompted
`CONSENT`	`TRUSTED`	`IMPLICIT`	Not prompted
`NONE`	`TRUSTED`	`FLEXIBLE`, `IMPLICIT`, or `REQUIRED`	Not prompted
`NONE`	`REQUIRED`	`FLEXIBLE` or `REQUIRED`	Prompted
`NONE`	`REQUIRED`	`IMPLICIT`	Not prompted

Note: When a scope is requested during a Client Credentials grant flow and CONSENT is set to FLEXIBLE, the scope is granted in the access token with no consent prompt. This occurs because there is no user involved in a two-legged OAuth Client Credentials grant flow.

Notes:

Apps created by /api/v1/apps default to consent_method=TRUSTED, while those created by /api/v1/clients default to consent_method=REQUIRED.
If you request a Scope that requires consent while using the client_credentials flow, an error is returned. Since there is no user, consent can't be given.
If the prompt value is set to NONE, but the consent_method and the consent values are set to REQUIRED, then an error occurs.
The Scope name must only contain printable ASCII characters, except for spaces, double quotes, and backslashes. It also must not start with okta. or okta: and must not be only okta or *.

Get all Scopes

GET /api/v1/authorizationServers/${authorizationServerId}/scopes

Get the Scopes defined for a specified Custom Authorization Server

Request parameters

Parameter	Description	Param Type	DataType	Required	Default
authorizationServerId	ID of a custom authorization server	URL	String	TRUE
q	Searches for scopes by `name`	Query	String	FALSE
filter	Filters scopes for a custom authorization server	Query	String	FALSE
after	Specifies the pagination cursor for the next page of scopes. Note: Treat the `after` cursor as an opaque value and obtain it through the next link relationship. See Pagination.	Query	String	FALSE
limit	Specifies the number of scope results on a page (max 200)	Query	Number	FALSE	200

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/scopes"

Response example

Returns the Scopes defined in the specified Custom Authorization Server

Get a Scope

GET /api/v1/authorizationServers/${authorizationServerId}/scopes/${scopeId}

Gets a Scope specified by the scopeId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
scopeId	ID of a Scope	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/scopes/${scopeId}"

Response example

Returns the Scope that you requested

Create a Scope

POST /api/v1/authorizationServers/${authorizationServerId}/scopes

Create a Scope for a Custom Authorization Server

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "description": "Drive car",
  "name": "car:drive",
  "consent": "REQUIRED"
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/scopes"

Response example

Returns the Scope that you created

Update a Scope

PUT /api/v1/authorizationServers/${authorizationServerId}/scopes/${scopeId}

Change the configuration of a Scope specified by the scopeId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
scopeId	ID of a Scope	String	True

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "description": "Order car",
  "name": "car:order",
  "consent": "REQUIRED",
  "metadataPublish": "ALL_CLIENTS"
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/scopes/${scopeId}"

Response example

Returns the Scope that you updated

Delete a Scope

DELETE /api/v1/authorizationServers/${authorizationServerId}/scopes/${scopeId}

Deletes a Scope specified by the scopeId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
scopeId	ID of a Scope	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/scopes/${scopeId}"

Response example

HTTP/1.1 204 No Content

Claim operations

Get all Claims
Get a Claim
Create a Claim
Update a Claim
Delete a Claim

Claim object

When you use these API endpoints to create or modify a Claim resource, the response looks like:

{
  "id": "{claimId}",
  "name": "sub",
  "status": "ACTIVE",
  "claimType": "RESOURCE",
  "valueType": "EXPRESSION",
  "value": "(appuser != null) ? appuser.userName : app.clientId",
  "alwaysIncludeInToken": "TRUE",
  "conditions": {
    "scopes": []
  },
  "system": true
}

Claim properties

Property	Description	Type	Required for create or update
alwaysIncludeInToken	Specifies whether to include Claims in the token Details	Boolean	False
claimType	Specifies whether the Claim is for an access token (`RESOURCE`) or ID token (`IDENTITY`)	Enum	True
conditions	Specifies the scopes for this Claim	Condition object	False
group_filter_type	Specifies the type of group filter if `valueType` is `GROUPS` Details	Enum	False
id	ID of the Claim	String	True except for create or get all Claims
name	Name of the Claim	String	True
status	Specifies whether requests have access to this Claim. Valid values: `ACTIVE` or `INACTIVE`	Enum	True
system	Specifies whether Okta created this Claim	Boolean	System
valueType	Specifies whether the Claim is an Okta Expression Language (EL) expression (`EXPRESSION`), a set of groups (`GROUPS`), or a system claim (`SYSTEM`)	Enum	True
value	Specifies the value of the Claim. This value must be a string literal if `valueType` is `GROUPS`, and the string literal is matched with the selected `group_filter_type`. The value must be an Okta EL expression if `valueType` is `EXPRESSION`.	String	True

Details for `group_filter_type`

If valueType is GROUPS, then the groups returned are filtered according to the value of group_filter_type:

STARTS_WITH: Group names start with value (not case-sensitive). For example, if value is group1, then group123 and Group123 are included.
EQUALS: Group name is the same as value (not case-sensitive). For example, if value is group1, then group1 and Group1 are included, but group123 isn't.
CONTAINS: Group names contain value (not case-sensitive). For example, if value is group1, then MyGroup123 and group1 are included.
REGEX: Group names match the regular expression in value (case-sensitive). For example if value is /^[a-z0-9_-]{3,16}$/, then any Group name that has at least three letters, no more than 16, and contains lowercase letters, a hyphen, or numbers.

If you have complex filters for Groups, you can create a Groups allowlist to put them all in a Claim.

Details for `alwaysIncludeInToken`

Always TRUE for access token Claims.
If FALSE for an ID token claim, the Claim won't be included in the ID token if ID token is requested with the access token or authorization_code, instead the client has to use the access token to get the Claims from the userinfo endpoint.

Get all Claims

GET /api/v1/authorizationServers/${authorizationServerId}/claims

Gets the Claims defined for a specified Custom Authorization Server

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/claims"

Response example

Returns the Claims defined in the specified Custom Authorization Server

Get a Claim

GET /api/v1/authorizationServers/${authorizationServerId}/claims/${claimId}

Returns the Claim specified by the claimId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
claimId	ID of a Claim	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/claims/${claimId}"

Response example

Returns the Claim that you requested

Create a Claim

POST /api/v1/authorizationServers/${authorizationServerId}/claims

Creates a Claim for a Custom Authorization Server

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "carDriving",
  "status": "ACTIVE",
  "claimType": "RESOURCE",
  "valueType": "EXPRESSION",
  "value": "\"driving!\"",
  "conditions": {
    "scopes": [
      "car:drive"
    ]
  }
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/claims"

Response example

Returns the Claim that you created

Update a Claim

PUT /api/v1/authorizationServers/${authorizationServerId}/claims/${claimId}

Changes the configuration of a Claim specified by the claimId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of an Authorization server	String	True
claimId	ID of a Claim	String	True

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "carDriving",
  "status": "ACTIVE",
  "claimType": "RESOURCE",
  "valueType": "EXPRESSION",
  "value": "\"driving!\"",
  "alwaysIncludeInToken": "true",
  "system": "false",
  "conditions": {
    "scopes": [
      "car:drive"
    ]
  }
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/claims/${claimId}"

Response example

Returns the Claim that you updated

Delete a Claim

DELETE /api/v1/authorizationServers/${authorizationServerId}/claims/${claimId}

Deletes a Claim specified by the claimId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of an Authorization server	String	True
claimId	ID of a Claim	String	True

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/claims/${claimId}"

Response example

HTTP/1.1 204 No Content

Key Store operations

Get Authorization Server Keys
Get Authorization Server Key
Rotate Authorization Server Keys

Note: Looking for how to obtain the jwks_uri for your org or custom authorization server? See the well-known OpenID metadata endpoint and the well-known OAuth 2.0 metadata endpoint.

Credentials object

When you use these API endpoints to create or modify a Credentials resource, the response looks like:

{
    "credentials": {
      "signing": {
        "rotationMode": "AUTO",
        "lastRotated": "2017-05-17T22:25:57.000Z",
        "nextRotation": "2017-08-15T22:25:57.000Z",
        "kid": "WYQxoK4XAwGFn5Zw5AzLxFvqEKLP79BbsKmWeuc5TB4",
        "use": "sig"
      }
    }
}

Credentials properties

Property	Description	DataType	Required	Updatable
kid	The ID of the JSON Web Key used for signing tokens issued by the Authorization Server	String	FALSE	FALSE
lastRotated	The timestamp when the Authorization Server started to use the `kid` for signing tokens	String	FALSE	FALSE
nextRotation	The timestamp when the Authorization Server changes the Key for signing tokens. Only returned when `rotationMode` is `AUTO`.	String	FALSE	FALSE
rotationMode	The Key rotation mode for the authorization server. Can be `AUTO` or `MANUAL`.	Enum	FALSE	TRUE
use	How the Key is used. Valid value: `sig`

Certificate JSON Web Key object

Defines a JSON Web Key Set (opens new window) for an application's signature or encryption credential

When you use these API endpoints to create or modify a Certificate JSON Web Key resource, the response looks like:

{
    "keys": [
        {
            "status": "ACTIVE",
            "alg": "RS256",
            "e": "AQAB",
            "n": "mZXlEiDy[...]Isor9Q",
            "kid": "WYQxoK4XAwGFn5Zw5AzLxFvqEKLP79BbsKmWeuc5TB4",
            "kty": "RSA",
            "use": "sig",
            "_links": {
              "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/default/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
              }
            }
        }
    ]
}

Key properties

Property	Description	Type
alg	The algorithm used with the Key. Valid value: `RS256`	String
e	RSA Key value (exponent) for Key blinding	String
kid	The certificate's Key ID	String
kty	Cryptographic algorithm family for the certificate's Key pair. Valid value: `RSA`	String
n	RSA modulus value	String
status	`ACTIVE`, `NEXT`, or `EXPIRED`	Enum
use	How the Key is used. Valid value: `sig`	String

Get Authorization Server Keys

GET /api/v1/authorizationServers/${authorizationServerId}/credentials/keys

Returns the current, future, and expired Keys used by the Custom Authorization Server

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/credentials/keys"

Response example

[
    {
        "status": "ACTIVE",
        "alg": "RS256",
        "e": "AQAB",
        "n": "g0MirhrysJMPm_wK45jvMbbyanfhl-jmTBv0o69GeifPaISaXGv8LKn3-CyJvUJcjjeHE17KtumJWVxUDRzFqtIMZ1ctCZyIAuWO0n
              LKilg7_EIDXJrS8k14biqkPO1lXGFwtjo3zLHeFSLw6sWf-CEN9zv6Ff3IAXb-RMYpfh-bVrxIgWsWCxjLW-UKI3la-gs0nWHH2PJr5HLJuI
              JIOL5HLJuIJIOLWahqTnm_r1LSCSYr6N4C-fh--w2_BW8DzTHalBYe76bNr0d7AqtR4tGazmrvrc79Wa2bjyxmhhN1u9jSaZQqq-3VZEod8q3,
              WHH2PJ5v1LoXniJQ4a2W8nDVqb6h4E8MUKYOpljTfQ",
        "kid": "RQ8DuhdxCczyMvy7GNJb4Ka3lQ99vrSo3oFBUiZjzzc",
        "kty": "RSA",
        "use": "sig",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    },
    {
        "status": "NEXT",
        "alg": "RS256",
        "e": "AQAB",
        "n": "l1hZ_g2sgBE3oHvu34T-5XP18FYJWgtul_nRNg-5xra5ySkaXEOJUDRERUG0HrR42uqf9jYrUTwg9fp-SqqNIdHRaN8EwRSDRsKAwK
              3 HIJ2NJfgmrrO2ABkeyUq6rzHxAumiKv1iLFpSawSIiTEBJERtUCDcjbbqyHVFuivIFgH8L37 - XDIDb0XG - R8DOoOHLJPTpsgH - rJe
              M5w96VIRZInsGC5OGWkFdtgk6OkbvVd7_TXcxLCpWeg1vlbmX - 0 TmG5yjSj7ek05txcpxIqYu - 7 FIGT0KKvXge_BOSEUlJpBhLKU28
              OtsOnmc3NLIGXB - GeDiUZiBYQdPR - myB4ZoQ ",
        "kid": "Y3vBOdYT-l-I0j-gRQ26XjutSX00TeWiSguuDhW3ngo",
        "kty": "RSA",
        "use": "sig",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    },
    {
        "status": "EXPIRED",
        "alg": "RS256",
        "e": "AQAB",
        "n": "lC4ehVB6W0OCtNPnz8udYH9Ao83B6EKnHA5eTcMOap_lQZ-nKtS1lZwBj4wXRVc1XmS0d2OQFA1VMQ-dHLDE3CiGfsGqWbaiZFdW7U
              GLO1nAwfDdH6xp3xwpKOMewDXbAHJlXdYYAe2ap - CE9c5WLTUBU6JROuWcorHCNJisj1aExyiY5t3JQQVGpBz2oUIHo7NRzQoKimvp
              dMvMzcYnTlk1dhlG11b1GTkBclprm1BmOP7Ltjd7aEumOJWS67nKcAZzl48Zyg5KtV11V9F9dkGt25qHauqFKL7w3wu - DYhT0hmyFc
              wn - tXS6e6HQbfHhR_MQxysLtDGOk2ViWv8AQ ",
        "kid": "h5Sr3LXcpQiQlAUVPdhrdLFoIvkhRTAVs_h39bQnxlU",
        "kty": "RSA",
        "use": "sig",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    }
]

The listed ACTIVE Key is used to sign tokens issued by the Authorization Server.
The listed NEXT Key is the next Key that the Authorization Server uses to sign tokens when Keys are rotated. The NEXT Key might not be listed if it hasn't been generated yet.
The listed EXPIRED Key is the previous Key that the Authorization Server used to sign tokens. The EXPIRED Key might not be listed if no Key has expired or the expired Key has been deleted.

Get Authorization Server Key

GET /api/v1/authorizationServers/${authorizationServerId}/credentials/keys/${keyId}

Returns the Key specified by the keyId

Request parameters

Parameter	Description	Type	Required
authorizationServerId	ID of a Custom Authorization Server	String	True
keyId	The certificate's Key ID	String	True

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/credentials/keys/${keyId}"

Response example

{
    "status": "NEXT",
    "alg": "RS256",
    "e": "AQAB",
    "n": "l1hZ_g2sgBE3oHvu34T-5XP18FYJWgtul_nRNg-5xra5ySkaXEOJUDRERUG0HrR42uqf9jYrUTwg9fp-SqqNIdHRaN8EwRSDRsKAwK
          3 HIJ2NJfgmrrO2ABkeyUq6rzHxAumiKv1iLFpSawSIiTEBJERtUCDcjbbqyHVFuivIFgH8L37 - XDIDb0XG - R8DOoOHLJPTpsgH - rJe
          M5w96VIRZInsGC5OGWkFdtgk6OkbvVd7_TXcxLCpWeg1vlbmX - 0 TmG5yjSj7ek05txcpxIqYu - 7 FIGT0KKvXge_BOSEUlJpBhLKU28
          OtsOnmc3NLIGXB - GeDiUZiBYQdPR - myB4ZoQ ",
    "kid": "Y3vBOdYT-l-I0j-gRQ26XjutSX00TeWiSguuDhW3ngo",
    "kty": "RSA",
    "use": "sig",
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

Rotate Authorization Server Keys

POST /api/v1/authorizationServers/${authorizationServerId}/credentials/lifecycle/keyRotate

Rotates the current Keys for a Custom Authorization Server. If you rotate Keys, the ACTIVE Key becomes the EXPIRED Key, the NEXT Key becomes the ACTIVE Key, and the Custom Authorization Server immediately begins using the new active Key to sign tokens.

Note: Okta rotates your Keys automatically in AUTO mode. You can rotate Keys yourself in either mode. If Keys are rotated manually, any intermediate cache should be invalidated and Keys should be fetched again using the Keys endpoint.

Request parameters

Parameter	Description	Param Type	DataType	Required
use	Purpose of the certificate. The only supported value is `sig`.	Body	String	True

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "use": "sig"
}' "https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/credentials/lifecycle/keyRotate"

Response example

[
    {
        "status": "ACTIVE",
        "alg": "RS256",
        "e": "AQAB",
        "n": "g0MirhrysJMPm_wK45jvMbbyanfhl-jmTBv0o69GeifPaISaXGv8LKn3-CyJvUJcjjeHE17KtumJWVxUDRzFqtIMZ1ctCZyIAuWO0n
              LKilg7_EIDXJrS8k14biqkPO1lXGFwtjo3zLHeFSLw6sWf-CEN9zv6Ff3IAXb-RMYpfh-bVrxIgWsWCxjLW-UKI3la-gs0nWHH2PJr5HLJuI
              JIOL5HLJuIJIOLWahqTnm_r1LSCSYr6N4C-fh--w2_BW8DzTHalBYe76bNr0d7AqtR4tGazmrvrc79Wa2bjyxmhhN1u9jSaZQqq-3VZEod8q3,
              WHH2PJ5v1LoXniJQ4a2W8nDVqb6h4E8MUKYOpljTfQ",
        "kid": "Y3vBOdYT-l-I0j-gRQ26XjutSX00TeWiSguuDhW3ngo",
        "kty": "RSA",
        "use": "sig",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    },
    {
        "status": "NEXT",
        "alg": "RS256",
        "e": "AQAB",
        "n": "l1hZ_g2sgBE3oHvu34T-5XP18FYJWgtul_nRNg-5xra5ySkaXEOJUDRERUG0HrR42uqf9jYrUTwg9fp-SqqNIdHRaN8EwRSDRsKAwK
              3 HIJ2NJfgmrrO2ABkeyUq6rzHxAumiKv1iLFpSawSIiTEBJERtUCDcjbbqyHVFuivIFgH8L37 - XDIDb0XG - R8DOoOHLJPTpsgH - rJe
              M5w96VIRZInsGC5OGWkFdtgk6OkbvVd7_TXcxLCpWeg1vlbmX - 0 TmG5yjSj7ek05txcpxIqYu - 7 FIGT0KKvXge_BOSEUlJpBhLKU28
              OtsOnmc3NLIGXB - GeDiUZiBYQdPR - myB4ZoQ ",
        "kid": "T5dZ1dYT-l-I0j-gRQ82XjutSX00TeWiSguuDhW3zdf",
        "kty": "RSA",
        "use": "sig",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    },
    {
        "status": "EXPIRED",
        "alg": "RS256",
        "e": "AQAB",
        "n": "lC4ehVB6W0OCtNPnz8udYH9Ao83B6EKnHA5eTcMOap_lQZ-nKtS1lZwBj4wXRVc1XmS0d2OQFA1VMQ-dHLDE3CiGfsGqWbaiZFdW7U
              GLO1nAwfDdH6xp3xwpKOMewDXbAHJlXdYYAe2ap - CE9c5WLTUBU6JROuWcorHCNJisj1aExyiY5t3JQQVGpBz2oUIHo7NRzQoKimvp
              dMvMzcYnTlk1dhlG11b1GTkBclprm1BmOP7Ltjd7aEumOJWS67nKcAZzl48Zyg5KtV11V9F9dkGt25qHauqFKL7w3wu - DYhT0hmyFc
              wn - tXS6e6HQbfHhR_MQxysLtDGOk2ViWv8AQ ",
        "kid": "RQ8DuhdxCczyMvy7GNJb4Ka3lQ99vrSo3oFBUiZjzzc",
        "kty": "RSA",
        "use": "sig",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/credentials/keys/{keyId}",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    }
]

Response example (error)

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: rotateKeys",
  "errorLink": "E0000001",
  "errorId": "oaeprak9qKHRlaWiclJ4oPJRQ",
  "errorCauses": [
    {
      "errorSummary": "Invalid value specified for key 'use' parameter."
    }
  ]
}

Shared Objects

Rule object
Conditions object

Rule object

{
  "type":"RESOURCE_ACCESS",
  "id":"0prbsjfyl01zfSZ9K0h7",
  "status":"ACTIVE",
  "name":"Default Policy Rule",
  "priority":1,
  "created":"2017-08-25T16:57:02.000Z",
  "lastUpdated":"2017-08-30T14:51:05.000Z",
  "system":false,
  "conditions":{
    "people":{
      "users":{
        "include":[

        ],
        "exclude":[

        ]
      },
      "groups":{
        "include":[
          "EVERYONE"
        ],
        "exclude":[

        ]
      }
    },
    "grantTypes":{
      "include":[
        "implicit",
        "client_credentials",
        "authorization_code",
        "password"
      ]
    },
    "scopes":{
      "include":[
        "*"
      ]
    }
  },
  "actions":{
    "token":{
      "accessTokenLifetimeMinutes":60,
      "refreshTokenLifetimeMinutes":0,
      "refreshTokenWindowMinutes":10080
    }
  },
  "_links":{
    "self":{
      "href":"https://{yourOktaDomain}/api/v1/authorizationServers/default/policies/{policyId}/rules/{rulesId}",
      "hints":{
        "allow":[
          "GET",
          "PUT",
          "DELETE"
        ]
      }
    },
    "deactivate":{
      "href":"https://{yourOktaDomain}/api/v1/authorizationServers/default/policies/{policyId}/rules/{rulesId}/lifecycle/deactivate",
      "hints":{
        "allow":[
          "POST"
        ]
      }
    }
  }
}

Rule properties

Property	Description	Data Type	Required for Create	Required for update
id	Identifier of the rule	String	Assigned	True
type	Rule type. Valid values: `RESOURCE_ACCESS`	String (Enum)	False	False
name	Name of the rule	String	True	True
status	Status of the rule: `ACTIVE` or `INACTIVE`	String (Enum)	False	False
priority	Priority of the rule	Integer	False	False
system	This is set to 'true' on system rules, which can't be deleted.	Boolean	False	False
created	Timestamp when the rule was created	Date	False	Assigned
lastUpdated	Timestamp when the rule was last modified	Date	False	Assigned
conditions	Conditions for rule	Conditions object	True	False
actions	Actions for rule, dictates lifetime of granted tokens	Actions Objects	False	False
_links	Hyperlinks	Links object	Assigned	False

Actions object

accessTokenLifetimeMinutes: minimum five minutes, maximum one day
refreshTokenLifetimeMinutes: minimum access token lifetime
refreshTokenWindowMinutes: minimum 10 minutes, maximum of five years

Example from a Rule object

{
"actions": {
    "token": {
      "accessTokenLifetimeMinutes": 60,
      "refreshTokenLifetimeMinutes": 0,
      "refreshTokenWindowMinutes": 10080
    }
  }
}

See also the Policy-Rule Actions object section

Conditions object

Example from a Rule object

{
  "conditions": {
    "people": {
      "users": {
        "include": [],
        "exclude": []
      },
      "groups": {
        "include": [
          "EVERYONE"
        ],
        "exclude": []
      }
    },
    "scopes": {
      "include": [
        "*"
      ]
    }
  }
}

Example from a Policy object

{
  "conditions": {
    "clients": {
      "include": [
        "ALL_CLIENTS"
      ]
    }
  }
}

Condition properties

Property	Description	Type	Required for create or update
clients	For Policies, specifies which clients are included in the Policy	`include` lists	True
grantTypes	Array of grantTypes that this condition includes. Accepted grantTypes: `authorization_code`, `password`, `refresh_token` or `client_credentials`. Determines the mechanism Okta uses to authorize the creation of the tokens.	`include` list	True
people	For rules, specifies which Users and Groups are included in the rule	`include` lists	True
scopes	Array of Scopes that this condition includes	`include` list	True

See also the Policy-Rule Conditions object section

Client Resource operations

List Client Resources for an Authorization Server

GET /api/v1/authorizationServers/${authorizationServerId}/clients

Lists all Client Resources for which the specified Authorization Server has tokens

Request parameters

Parameter	Description	Parameter Type	DataType	Required
authorizationServerId	ID of the Authorization Server	URL	String	TRUE

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/clients"

Response example

[
    {
        "client_id": "0oabskvc6442nkvQO0h7",
        "client_name": "My App",
        "client_uri": null,
        "logo_uri": null,
        "_links": {
            "tokens": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/clients/{clientId}/tokens"
            }
        }
    }
]

List Client Resources for a specified Policy

GET /api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/clients

Lists all Client Resources for which the specified Policy is configured.

Request parameters

Parameter	Description	Parameter Type	DataType	Required
authorizationServerId	ID of the Authorization Server	URL	String	TRUE
policyId	ID of a Policy	URL	String	TRUE

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/policies/${policyId}/clients"

Response example

[
    {
        "client_id": "0oabskvc6442nkvQO0h7",
        "client_id_issued_at": 1651642760,
        "client_secret_expires_at": 0,
        "client_name": "My App",
        "client_uri": null,
        "logo_uri": null,
        "redirect_uris": [],
        "response_types": ["token"],
        "grant_types": ["client_credentials"],
        "token_endpoint_auth_method": "client_secret_basic",
        "application_type": "service"
    }
]

OAuth 2.0 token management operations

List refresh tokens
Get refresh token
Revoke all refresh tokens
Revoke refresh token

These endpoints allow you to manage tokens issued by an Authorization Server for a particular client. For example, you could revoke every active refresh token for a specific client. You can also revoke specific tokens or manage tokens at the User level.

Read Validate access tokens and Validate ID tokens to understand more about how OAuth 2.0 tokens work.

List refresh tokens

GET /api/v1/authorizationServers/${authorizationServerId}/clients/${clientId}/tokens

Lists all refresh tokens issued by an Authorization Server for a specific client

Request parameters

Parameter	Description	Param Type	DataType	Required	Default
after	Specifies the pagination cursor for the next page of tokens	Query	String	FALSE
authorizationServerId	ID of the Authorization Server	URL	String	TRUE
clientId	ID of the client	URL	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE
limit	The maximum number of tokens to return (maximum 200)	Query	Number	FALSE	20

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}/clients/${clientId}/tokens"

Response example

[
  {
    "id": "oar579Mcp7OUsNTlo0g3",
    "status": "ACTIVE",
    "created": "2018-03-09T03:18:06.000Z",
    "lastUpdated": "2018-03-09T03:18:06.000Z",
    "expiresAt": "2018-03-16T03:18:06.000Z",
    "issuer": "https://{yourOktaDomain}/oauth2/{authorizationServerId}",
    "clientId": "{clientId}",
    "userId": "{userId}",
    "scopes": [
      "offline_access",
      "car:drive"
    ],
    "_links": {
      "app": {
        "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
        "title": "Native"
      },
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/clients/{clientId}/tokens/{tokenId}"
      },
      "revoke": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}/clients/{clientId}/tokens/{tokenId}",
        "hints": {
          "allow": [
            "DELETE"
          ]
        }
      },
      "client": {
        "href": "https://{yourOktaDomain}/oauth2/v1/clients/{clientId}",
        "title": "Example Client App"
      },
      "user": {
        "href": "https://{yourOktaDomain}/api/v1/users/{userId}",
        "title": "Saml Jackson"
      },
      "authorizationServer": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/{authorizationServerId}",
        "title": "Example Authorization Server"
      }
    }
  }
]

Get refresh token

GET /api/v1/authorizationServers/${authorizationServerId}/clients/${clientId}/tokens/${tokenId}

Gets a refresh token issued by an Authorization Server for the specified client

Request parameters

Parameter	Description	Param Type	DataType	Required
authorizationServerId	ID of the Authorization Server	URL	String	TRUE
clientId	ID of the client	URL	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE
tokenId	ID of the token	URL	String	TRUE

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/default/clients/${clientId}/tokens/${tokenId}?expand=scope"

Response example

{
  "id": "oar579Mcp7OUsNTlo0g3",
  "status": "ACTIVE",
  "created": "2018-03-09T03:18:06.000Z",
  "lastUpdated": "2018-03-09T03:18:06.000Z",
  "expiresAt": "2018-03-16T03:18:06.000Z",
  "issuer": "https://{yourOktaDomain}/oauth2/default",
  "clientId": "{clientId}",
  "userId": "{userId}",
  "scopes": [
    "offline_access",
    "car:drive"
  ],
  "_embedded": {
    "scopes": [
      {
        "id": "{scopeId}",
        "name": "offline_access",
        "description": "Requests a refresh token by default, used to obtain more access tokens without re-prompting the user for authentication.",
        "_links": {
          "scope": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/default/scopes/{scopeId}",
            "title": "offline_access"
          }
        }
      },
      {
        "id": "scp142iq2J8IGRUCS0g4",
        "name": "car:drive",
        "displayName": "Drive car",
        "description": "Allows the user to drive a car.",
        "_links": {
          "scope": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/default/scopes/{scopeId}",
            "title": "Drive car"
          }
        }
      }
    ]
  },
  "_links": {
    "app": {
      "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
      "title": "Native"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/default/clients/{clientId}/tokens/{tokenId}"
    },
    "revoke": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/default/clients/{clientId}/tokens/{tokenId}",
      "hints": {
        "allow": [
          "DELETE"
        ]
      }
    },
    "client": {
      "href": "https://{yourOktaDomain}/oauth2/v1/clients/{clientId}",
      "title": "Example Client App"
    },
    "user": {
      "href": "https://{yourOktaDomain}/api/v1/users/{userId}",
      "title": "Saml Jackson"
    },
    "authorizationServer": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/default",
      "title": "Example Authorization Server"
    }
  }
}

Revoke all refresh tokens

DELETE /api/v1/authorizationServers/${authorizationServerId}/clients/${clientId}/tokens

Revokes all refresh tokens issued by an Authorization Server for the specified client. Any access tokens issued with these refresh tokens are also revoked, but access tokens issued without a refresh token aren't affected.

Request parameters

Parameter	Description	Parameter Type	DataType	Required
authorizationServerId	ID of the Authorization Server	URL	String	TRUE
clientId	ID of the client	URL	String	TRUE

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/default/clients/${clientId}/tokens"

Response example

HTTP/1.1 204 No Content

Revoke refresh token

DELETE /api/v1/authorizationServers/${authorizationServerId}/clients/${clientId}/tokens/${tokenId}

Revokes the specified refresh token. If an access token was issued with this refresh token, it is also revoked.

Request parameters

Parameter	Description	Parameter Type	DataType	Required
authorizationServerId	ID of the Authorization Server	URL	String	TRUE
clientId	ID of the client	URL	String	TRUE
tokenId	ID of the token	URL	String	TRUE

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authorizationServers/default/clients/${clientId}/tokens/${tokenId}"

Response example

HTTP/1.1 204 No Content

Edit This Page On GitHub

On this page

Authorization Servers API

Get started

Authorization Server operations

Work with the Default Authorization Server

Authorization Server object

Authorization Server properties

Property details

Create Authorization Server

Request parameters

Request example

Response example

List Authorization Servers

Request parameters

Request example

Response example

Get Authorization Server

Request parameters

Request example

Response example

Update Authorization Server

Request parameters

Request example

Response example

Delete Authorization Server

Request parameters

Request example

Response example

Activate Authorization Server

Request parameters

Request example

Response example

Deactivate Authorization Server

Request parameters

Request example

Response example

Policy operations

Policy object

Policy properties

Get all Policies

Request parameters

Request example

Response example

Get a Policy

Request parameters

Request example

Response example

Create a Policy

Request parameters

Request example

Response example

Update a Policy

Request parameters

Request example

Response example

Delete a Policy

Request parameters

Request example

Response example

Activate a Policy

Request parameters

Request example

Response example

Deactivate a Policy

Request parameters

Request example

Response example

Policy Rule operations

Policy Rule Object

Get all Policy Rules

Request parameters

Request example

Response example

Get a Policy Rule

Request parameters

Request example

Response example

Create a Policy Rule

Request parameters

Request example

Details for `group_filter_type`

Details for `alwaysIncludeInToken`