Authorization Servers

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.

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

List all Authorization Servers
OAuth 2.0: okta.authorizationServers.read

Lists all custom authorization servers in the org

Request
query Parameters
q
string

Searches the name and audiences of authorization servers for matching values

Example: q=customasone
limit
integer <int32>
Default: 200

Specifies the number of authorization server results on a page. Maximum value: 200

after
string

Specifies the pagination cursor for the next page of authorization servers. Treat as an opaque value and obtain through the next link relationship.

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/authorizationServers
Request samples
Response samples
application/json
[]

Create an Authorization Server
OAuth 2.0: okta.authorizationServers.manage

Creates an authorization server

Request
Request Body schema: application/json
required
audiences
Array of strings

The recipients that the tokens are intended for. This becomes the aud claim in an access token. Okta currently supports only one audience.

object (AuthorizationServerCredentials)
object (AuthorizationServerCredentialsSigningConfig)
rotationMode
string (AuthorizationServerCredentialsRotationMode)

The Key rotation mode for the authorization server

Enum: "AUTO" "MANUAL"
use
string (AuthorizationServerCredentialsUse)

How the key is used

Value: "sig"
description
string

The description of the custom authorization server

issuer
string

The complete URL for the custom authorization server. This becomes the iss claim in an access token.

issuerMode
string

Indicates which value is specified in the issuer of the tokens that a custom authorization server returns: the Okta org domain URL or a custom domain URL.

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.

When set to ORG_URL, then in responses, issuer is the Okta org domain URL: https://${yourOktaDomain}.

When set to CUSTOM_URL, then in responses, issuer is the custom domain URL configured in the administration user interface.

When 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.

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 they're changed using the Admin Console or the API. This way, existing integrations with the client and resource server continue to work after the feature is enabled.

name
string

The name of the custom authorization server

status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
Responses
201

Created

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/authorizationServers
Request samples
application/json
{
  • "name": "Sample Authorization Server",
  • "description": "Sample Authorization Server description",
  • "audiences": [
    • "api://default"
    ]
}
Response samples
application/json
{}

Retrieve an Authorization Server
OAuth 2.0: okta.authorizationServers.read

Retrieves an authorization server

Request
path Parameters
authServerId
required
string

id of the Authorization Server

Example: GeGRTEr7f3yu2n7grw22
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/authorizationServers/{authServerId}
Request samples
Response samples
application/json
{}

Replace an Authorization Server
OAuth 2.0: okta.authorizationServers.manage

Replaces an authorization server

Request
path Parameters
authServerId
required
string

id of the Authorization Server

Example: GeGRTEr7f3yu2n7grw22
Request Body schema: application/json
required
audiences
Array of strings

The recipients that the tokens are intended for. This becomes the aud claim in an access token. Okta currently supports only one audience.

object (AuthorizationServerCredentials)
object (AuthorizationServerCredentialsSigningConfig)
rotationMode
string (AuthorizationServerCredentialsRotationMode)

The Key rotation mode for the authorization server

Enum: "AUTO" "MANUAL"
use
string (AuthorizationServerCredentialsUse)

How the key is used

Value: "sig"
description
string

The description of the custom authorization server

issuer
string

The complete URL for the custom authorization server. This becomes the iss claim in an access token.

issuerMode
string

Indicates which value is specified in the issuer of the tokens that a custom authorization server returns: the Okta org domain URL or a custom domain URL.

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.

When set to ORG_URL, then in responses, issuer is the Okta org domain URL: https://${yourOktaDomain}.

When set to CUSTOM_URL, then in responses, issuer is the custom domain URL configured in the administration user interface.

When 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.

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 they're changed using the Admin Console or the API. This way, existing integrations with the client and resource server continue to work after the feature is enabled.

name
string

The name of the custom authorization server

status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/authorizationServers/{authServerId}
Request samples
application/json
{
  • "name": "New Authorization Server",
  • "description": "Authorization Server description",
  • "audiences": [
    • "api://default"
    ],
  • "credentials": {
    • "signing": {
      }
    },
  • "issuerMode": "ORG_URL",
  • "status": "ACTIVE"
}
Response samples
application/json
{}

Delete an Authorization Server
OAuth 2.0: okta.authorizationServers.manage

Deletes an authorization server

Request
path Parameters
authServerId
required
string

id of the Authorization Server

Example: GeGRTEr7f3yu2n7grw22
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/authorizationServers/{authServerId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Activate an Authorization Server
OAuth 2.0: okta.authorizationServers.manage

Activates an authorization server

Request
path Parameters
authServerId
required
string

id of the Authorization Server

Example: GeGRTEr7f3yu2n7grw22
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/authorizationServers/{authServerId}/lifecycle/activate
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Deactivate an Authorization Server
OAuth 2.0: okta.authorizationServers.manage

Deactivates an authorization server

Request
path Parameters
authServerId
required
string

id of the Authorization Server

Example: GeGRTEr7f3yu2n7grw22
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/authorizationServers/{authServerId}/lifecycle/deactivate
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}