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
API Access Management
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
API Access Management
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
API Access Management
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
API Access Management
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": {
      }
    },
  • "issuer": "https://{yourOktaDomain}/oauth2/{authorizationServerId}",
  • "issuerMode": "ORG_URL",
  • "status": "ACTIVE"
}
Response samples 
application/json
{}
Delete an authorization server
API Access Management
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
API Access Management
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
API Access Management
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": [ ]
}