Custom Authorization Servers

Use a custom authorization server to create and apply authorization policies to secure your APIs. An access token that's minted by a custom authorization server is consumed by your APIs.

Note: Okta has two types of authorization servers: the org authorization server and the custom authorization server. To learn more about each type of authorization server and when to use them, see Authorization servers.

You can create multiple custom authorization servers within a single Okta org that you can use to protect your own resource servers. Within each authorization server, define your own custom OAuth 2.0 scopes, claims, and access policies to support authorization for your APIs.

Retrieve the OAuth 2.0 metadata
CORSAPI Access Management

Returns OAuth 2.0 metadata for the specified custom authorization server. This information can be used by clients to programmatically configure their interactions with Okta. Custom scopes are returned only when they are configured to be publicly discoverable. Custom claims are never returned.

Request
path Parameters
authorizationServerId
required
string

id of the Authorization Server

query Parameters
client_id
string

Clients can be configured to format the issuer differently. Pass in the client_id to ensure the returned issuer format matches.

Responses
200

Success

400

Invalid Client ID

404

Authorization Server Not Found

get/oauth2/{authorizationServerId}/.well-known/oauth-authorization-server
Request samples 
Response samples 
application/json
{}
Retrieve the OpenID Connect metadata
CORSAPI Access Management
Returns OpenID Connect metadata for the specified custom authorization server. This information can be used by clients to programmatically configure their interactions with Okta. Custom scopes are returned only when they are configured to be publicly discoverable. Custom claims are never returned.


Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
query Parameters
client_id
string
Clients can be configured to format the issuer differently. Pass in the client_id to ensure the returned issuer format matches.


 
Responses 
200
Success


400
Invalid Client ID


404
Authorization Server Not Found


get/oauth2/{authorizationServerId}/.well-known/openid-configuration
Request samples 
Response samples 
application/json
{}
/authorize
This is a starting point for browser-based OpenID Connect flows such as the implicit and authorization code flows. This request authenticates the user and returns tokens along with an authorization grant to the client application as a part of the callback response.




Note: Requests to the /authorize endpoint should redirect the browser (user agent) to the endpoint. You can't use AJAX with this endpoint. Example responses are intentionally omitted, but include displaying a sign-in prompt, redirecting to the client application, or displaying an error.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
query Parameters
acr_values
string (AcrValue) 
An optional parameter that can be included in the authentication request. This parameter increases the level of user assurance.




Note: Multiple space-delimited values may be provided. The authorization server chooses one and reflects the chosen value in any resulting tokens.




 Enum: Description
phr
 Phishing-Resistant. Requires users to provide possession factors that cryptographically verify the sign-in server (the origin). Currently, only FIDO2/WebAuthn satisfies this requirement. Because phishing resistance implies device binding, that constraint is selected automatically when phr is specified.


phrh
 Phishing-Resistant Hardware-Protected. Requires that you store keys being used to authenticate in secure hardware (TPM, Secure Enclave) on the device. Currently, only Okta Verify meets this constraint. Because hardware protection implies device binding, that constraint is selected automatically when phrh is specified.


urn:okta:loa:1fa:any
Any one factor. Allows one factor authentication with no requirements on which factor.


urn:okta:loa:1fa:pwd
Password only. Allows one factor authentication that requires the user’s password.


urn:okta:loa:2fa:any
Any two factors. Allows two factor authentication with no requirements on which factors.


urn:okta:loa:2fa:any:ifpossible
 Any two factors, if possible. Allows two factor authentication with no requirements on which factors. Any two factors are presented only if the user is enrolled, otherwise any one factor is presented.


 
client_id
required
string
Obtained during either manual client registration or through the Dynamic Client Registration API. It identifies the client and must match the value preregistered in Okta.


 
code_challenge
string
A challenge for PKCE. The challenge is verified in the access token request.


 
code_challenge_method
string (CodeChallengeMethod) 
Method used to derive the code challenge for PKCE.


 Value: "S256"  
display
string
The display parameter to be passed to the external Identity Provider when performing social login.


 
enroll_amr_values
string (AmrValue) 
A space-delimited list of values indicating which authenticators to enroll in.


    

  • If the enroll_amr_values parameter is specified, then the value for prompt must be enroll_authenticator.
    • 

  • The parameter value is space-delimited, for example, pwd sms okta_verify is a valid request parameter value. You are prompted in the order of the amr values provided.
    • 



 Enum: "duo" "email" "fed" "google_otp" "kba" "oath_otp" "okta_verify" "opt" "pop" "pwd" "rsa" "sms" "symantec" "tel" "yubikey"  
idp_scope
string
An Okta Extension to the OpenID specification. A space-delimited list of scopes to be provided to the external Identity Provider when performing social login. These scopes are used in addition to the scopes already configured for the Identity Provider.


 
idp
string
An Okta Extension to the OpenID Specification. The ID of the Identity Provider to use if there's no Okta Session.


 
login_hint
string
A username to pre-populate if prompting for authentication


 
max_age
integer
Allowable elapsed time, in seconds, since the last time the end user was actively authenticated by Okta.


 
nonce
string
A value that is returned in the ID token. It is used to mitigate replay attacks. The value is required for Implicit and Hybrid flows, but optional for Auth Code flows. See OIDC Specs.


 
prompt
string (Prompt) 
If no prompt parameter is specified, the standard behavior occurs:


    

  • If an Okta session already exists and meets the assurance requirements of the app, the user is silently authenticated. Otherwise, the user is prompted to authenticate.
    • 

  • If scopes are requested that require consent and consent isn't yet given by the authenticated user, the user is prompted to give consent.
    • 



 Enum: Description
none
Don't prompt for authentication or consent. If an Okta session already exists, the user is silently authenticated. Otherwise, an error is returned.


login
Always prompt the user for authentication, regardless of whether they have an Okta session.


consent
Depending on the values set for consent_method in the app and consent for the scope, display the Okta consent dialog, even if the user has already given consent. User consent is available for custom authorization servers (requires the API Access Management feature and the User Consent feature enabled).


login consent
Can also be consent login (order doesn't matter). The user is always prompted for authentication, and the user consent dialog appears depending on the values set for consent_method in the app and consent on the scope, even if the user has already given consent.


enroll_authenticator
This indicates that the intent is to enroll the user with an authenticator. The following other parameters must be used together with this value for a valid request:


    

  • enroll_amr_values: Value must be specified and indicates which authenticator method you're allowing the user to enroll.
    • 

  • response_type: Value must be none, which means no tokens should be returned at the end of the flow.
    • 

  • acr_values: Value must be urn:okta:loa:2fa:any:ifpossible, which means the user is prompted for at least one factor before enrollment.
    • 

  • max_age: Value must be 0, which means no existing session should be considered.
    • 

  • scope and nonce must not be specified, because no tokens are generated.
    • 



 
redirect_uri
required
string
Callback location where the authorization code or tokens should be sent. It must match the value preregistered in Okta during client registration.


 
response_type
required
string (ResponseTypesSupported) 
Any combination of code, token, and id_token. The combination determines the flow.


 Enum: "code" "code id_token" "code id_token token" "code token" "id_token" "id_token token" "token"  
response_mode
string (ResponseMode) 
How the authorization response should be returned. If id_token or token is specified in the response_type, then query isn't allowed as a response mode. Defaults to fragment in implicit and hybrid flows.


The Referrer-Policy header is automatically included in the response when either the fragment or query parameter values are used. The header is set to Referrer-Policy: no-referrer.


 Enum: Description
fragment
Parameters are encoded in the URL fragment added to the redirect_uri when redirecting back to the client.


query
Parameters are encoded in the query string added to the redirect_uri when redirecting back to the client.


form_post
Parameters are encoded as HTML form values (application/x-www-form-urlencoded format) and are transmitted through the HTTP POST method to the client.


okta_post_message
Uses HTML5 Web Messaging (for example, window.postMessage()) instead of the redirect for the authorization response from the /authorize endpoint.


okta_post_message is an adaptation of the Web Message Response Mode.
This value provides a secure way for a single-page application to perform a sign-in flow in a pop-up window or an iFrame and receive the ID token, access token, and/or authorization code back in the parent page without leaving the context of that page.


Use the postMessage() data object to help you when working with the okta_post_message value of the response_mode request parameter.






Parameter
Description
Data Type





access_token
An access token. This is returned if the response_type included token.
string




error
The error code, if something went wrong
string




error_description
Additional error information (if any)
string




id_token
An ID token. This is returned if the response_type includes id_token.
string




state
The unmodified state value from the request
string





 
request_uri
string
Location where the authorization request payload data is referenced in an authorization request to the /authorize endpoint. This is returned from a Pushed Authorization Request at the /par endpoint.


 
request
string
A JWT created by the client that enables requests to be passed as a single, self-contained parameter.


    

  • You must sign the JWT using either the app's client secret or a private key whose public key is registered on the app's JWKSet.
    • 

  • The JWT can't be encrypted.
    

     Note: See Build a JWT for client authentication for information on how to build a JWT.
    

    

    • 

  • Okta supports the HMAC, RSA and ECDSA signature algorithms. HMAC signatures require that the client has a token_endpoint_auth_method that uses a client_secret. RSA and ECDSA signatures requires that the client registers a public key.
    • 

  • We recommend that you don't duplicate any request parameters in both the JWT and the query URI itself. However, you can do so with state, nonce, code_challenge, and code_challenge_method. In those cases, the values in the JWT overrides the query URI values.
    • 

  • Okta validates the request parameter in the following ways:
      

    1. iss is required and must be the client_id.
      2. 

    2. aud is required and must be the same value as the Authorization Server issuer that mints the ID or access token. This value is published in the metadata for your Authorization Server.
      3. 

    3. JWT lifetime is evaluated using the iat and exp claims, if present. If the JWT is expired or not yet valid, Okta returns an invalid_request_object error. Okta rejects JWTs that expire more than one hour in the future.
      4. 

    4. Okta rejects the JWT if the jti claim is present and it has already been processed.
      5. 

    

    • 



 
scope
required
string
A space-delimited string of scopes requested


 
sessionToken
string
Okta one-time session token. This is an Okta extension to the OpenID specification. The sessionToken allows an API-based user sign-in flow.


 
state
required
string
A value to be returned with the token. The client application can use it to remember the state of its interaction with the end user at the time of the authentication call. It can contain alphanumeric, comma, period, underscore, and hyphen characters. 


Okta requires the OAuth 2.0 state parameter on all requests to the /authorize endpoint to prevent cross-site request forgery (CSRF).
The OAuth 2.0 specification requires that clients protect their redirect URIs against CSRF by sending a value in the authorize request that binds the request to the user-agent's authenticated state.
Using the state parameter is also a countermeasure to several other known attacks as outlined in OAuth 2.0 Threat Model and Security Considerations.


 
Responses 
429
Too Many Requests


get/oauth2/{authorizationServerId}/v1/authorize
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000047",
  • "errorSummary": "You exceeded the maximum number of requests. Try again in a while.",
  • "errorLink": "E0000047",
  • "errorId": "sampleQPivGUj_ND5v78vbYWW",
  • "errorCauses": [ ]
}
/bc/authorize
This endpoint returns a unique identifier (auth_req_id) that identifies the authentication flow while it tries to authenticate the user in the background. This auth_req_id value is used in subsequent token requests to the /token endpoint.




Note: The /bc/authorize endpoint requires client authentication. The method is configured per client application. See Client authentication methods for more information.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
binding_message
string
A message that appears for the user to identify the transaction.


 
id_token_hint
required
string
An ID token previously issued to the client as a hint to identify the user for whom authentication is being requested.


Note: You can specify either login_hint or id_token_hint in the authentication request, not both.


 
login_hint
required
string
A hint to the OpenID Provider regarding the user for whom authentication is being requested.


Note: You can specify either login_hint or id_token_hint in the authentication request, not both.


 
request
string
A JWT created by the client that enables requests to be passed as a single, self-contained parameter.




 Note: See Build a JWT for client authentication for information on how to build a JWT.




    

  • You must sign the JWT using either the app's client secret or a private key whose public key is registered on the app's JWKSet.
    • 

  • You can't encrypt the JWT.
    • 

  • Okta supports the HMAC, RSA and ECDSA signature algorithms. HMAC signatures require that the client has a token_endpoint_auth_method that uses a client_secret. RSA and ECDSA signatures require that the client registers a public key.
    • 

  • You must specify backchannel_authentication_request_signing_alg either during client registration or when updating the client to use the signed authentication requests.
    • 

  • Okta validates the request parameter in the following ways:
      

    1. iss is required and must be the client_id.
      2. 

    2. aud is required and must be the same value as the authorization server issuer that mints the ID or access token. This value is published in the metadata for your authorization server.
      3. 

    3. JWT lifetime is evaluated using the iat and exp claims, if present. If the JWT is expired or not yet valid, Okta returns an invalid_request_object error. Okta rejects JWTs that expire more than one hour in the future.
      4. 

    4. Okta rejects the JWT if the jti claim is present and it's already been processed.
      5. 

    

    • 



 
request_expiry
integer  [ 1 .. 300 ] 
Allows the client to request the expires_in value in number of seconds for the auth_req_id that the server returns.


 
scope
required
string
openid is required for authentication requests. You can also include other scopes.


 
property name*
additional property
any
 
Responses 
200
Success


400
Bad Request


401
Unauthorized


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/bc/authorize
Request samples 
application/x-www-form-urlencoded
client_id=0jrabyQWm4B9zVJPbotY&client_secret=6W7XvLCrs4ByKn7Ucwh8ygeeXRhdGFdVOTp75eOc&scope=openid&binding_message=Signing%20in%20from%20device&login_hint=john.doe%40example.com
Response samples 
application/json
{
  • "auth_req_id": "ftJwF5ZwW2SGPPoTQEKtAr_U8_Ek3RvWyR",
  • "expires_in": 300,
  • "interval": 5
}
/challenge
Initiates the challenge of subsequent factor(s) in a Direct Authentication flow after the token endpoint has responded with 'mfa_required'. This endpoint is optional if the client is able to proceed without it, for example, the client knows it needs to follow up with an OTP and can prompt the end user for one.




Note: The /challenge endpoint requires client authentication. The method is configured per client application. See Client authentication methods.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
challenge_types_supported
Array of strings (ChallengeType) 
List of direct authentication challenge types supported by the client


Items Enum: "http://auth0.com/oauth/grant-type/mfa-oob" "http://auth0.com/oauth/grant-type/mfa-otp"  
channel_hint
string (Channel) 
The out-of-band channel for use with authentication. Required for all /oob-authenticate requests and any /challenge request with an out-of-band authenticator.


 Enum: "push" "sms" "voice"  
mfa_token
required
string
The value returned from a previous token or challenge request for identifying the multifactor transaction across multiple requests


 
Responses 
200
The next factor type to challenge is returned and in the case of out-of-band factors, any information needed for the out-of-band transaction.


400
Bad Request


401
Unauthorized


403
Forbidden


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/challenge
Request samples 
application/x-www-form-urlencoded
mfa_token=Qwk9va6QYgR3s7JMiWUm&channel_hint=push&challenge_types_supported=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob
Response samples 
application/json
{}
/device/authorize
CORS
Returns a user code, device code, activation link, and QR code activation link


Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
client_id
string
Obtained during either manual client registration or through the Dynamic Client Registration API. It identifies the client and must match the value preregistered in Okta.


 
scope
string
A list of scopes that the client wants included in the access token.


 
Responses 
200
Based on the type of token and whether it is active, the returned JSON contains a different set of information.


400
Bad Request


401
Unauthorized


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/device/authorize
Request samples 
application/x-www-form-urlencoded
client_id=string&scope=string
Response samples 
application/json
{}
/introspect
CORS
This endpoint takes an access token, ID token, refresh token, or device secret and returns a boolean that indicates whether it is active. If the token is active, additional data about the token is also returned. If the token is invalid, expired, or revoked, it is considered inactive.


Be sure that you are using the /introspect endpoint of the same authorization server that you used to create the token.




Note: The /introspect endpoint requires client authentication. The method is configured per client application. See Client authentication methods for more information. For public clients (such as single-page and mobile apps) that don't have a client_secret, you must include the client_id as a query parameter when calling the /introspect endpoint. Make sure that you aren't passing the Authorization header in the request.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
token
string
An access token, ID token, refresh token, or a device secret.




Note: Although ID tokens can be sent to this endpoint, they are usually validated on the service provider or app side of a flow.




 
token_type_hint
string (TokenTypeHintIntrospect) 
Indicates the type of token being passed


 Enum: "access_token" "device_secret" "id_token" "refresh_token"  
Responses 
200
Based on the type of token and whether it is active, the returned JSON contains a different set of information.


400
Bad Request


401
Unauthorized


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/introspect
Request samples 
application/x-www-form-urlencoded
token=string&token_type_hint=access_token
Response samples 
application/json
{
  • "active": true,
  • "token_type": "Bearer",
  • "scope": "openid profile",
  • "client_id": "a9VpZDRCeFh3Nkk2VdYa",
  • "username": "john.doe@example.com",
  • "exp": 1451606400,
  • "iat": 1451602800,
  • "sub": "john.doe@example.com",
  • "aud": "https://{yourOktaDomain}",
  • "iss": "https://{yourOktaDomain}/oauth2/orsmsg0aWLdnF3spV0g3",
  • "jti": "AT.7P4KlczBYVcWLkxduEuKeZfeiNYkZIC9uGJ28Cc-YaI",
  • "uid": "00uid4BxXw6I6TV4m0g3"
}
/keys
CORS
Returns a JSON Web Key Set (JWKS) that contains the public keys that can be used to verify the signatures of tokens that you receive from your authorization server.




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




Any of the two or three keys listed are used to sign tokens. The order of keys in the result doesn't indicate which keys are used.


These keys can be used to locally validate JWTs returned by Okta. Standard open-source libraries are available for every major language to perform JWS signature validation.




Note: The information returned from this endpoint could lag slightly, but will eventually be up-to-date.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Responses 
200
Success


429
Too Many Requests


get/oauth2/{authorizationServerId}/v1/keys
Request samples 
Response samples 
application/json
{
  • "keys": [
    • {
      },
    • {
      },
    • {
      }
    ]
}
/logout
Use this operation to sign a user out by removing their Okta browser session.


This endpoint takes an ID token and logs the user out of Okta if the subject matches the current Okta session. A post_logout_redirect_uri may be specified to redirect the browser after the logout is performed. Otherwise, the browser is redirected to the Okta sign-in page. See Sign users out for more information.


If no Okta session exists, this endpoint has no effect and the browser is redirected immediately to the Okta sign-in page or the post_logout_redirect_uri (if specified).


If the ID token passed using id_token_hint is invalid, the browser is redirected to an error page.


If the ID token is valid, but expired, and the subject matches the current Okta session, a logout request signs the user out and redirects the browser to the post_logout_redirect_uri.




Note: Requests to the /logout endpoint should redirect the browser (user agent) to the endpoint. You can't use AJAX with this endpoint. We may load an interstitial to do client-side logic before finally redirecting to the post_logout_redirect_uri or sign-in page if no redirect is provided.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
query Parameters
id_token_hint
required
string
A valid ID token with a subject that matches the current session.


 
post_logout_redirect_uri
string
Location to redirect to after the logout is performed. It must match the value preregistered in Okta during client registration.


 
state
string
An optional value that's returned as a query parameter during the redirect at the end of the flow


 
Responses 
200
Successful logout


429
Too Many Requests


get/oauth2/{authorizationServerId}/v1/logout
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000047",
  • "errorSummary": "You exceeded the maximum number of requests. Try again in a while.",
  • "errorLink": "E0000047",
  • "errorId": "sampleQPivGUj_ND5v78vbYWW",
  • "errorCauses": [ ]
}
/logout
Use this operation to sign a user out by removing their Okta browser session. This is the recommended method over GET as you can wrap the parameters in the request body.


This endpoint uses the ID token to verify that the subject matches the current Okta session, and then signs the user. You can specify a post_logout_redirect_uri to redirect the browser after the user is signs out. Otherwise, the browser is redirected to the Okta sign-in page. See Sign users out.


If no Okta session exists, this endpoint has no effect and the browser is redirected immediately to the Okta sign-in page or the post_logout_redirect_uri (if specified).


If the ID token passed using id_token_hint is invalid, the browser is redirected to an error page.


If the ID token is valid, but expired, and the subject matches the current Okta session, a logout request signs the user out and redirects the browser to the post_logout_redirect_uri.




Note: When making requests to the /logout endpoint, the browser (user agent) should be redirected to the endpoint. You need to make a POST request from a form. A POST request to this endpoint from the backend doesn't completely terminate the session.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
id_token_hint
required
string
A valid ID token with a subject that matches the current session


 
post_logout_redirect_uri
string
Location to redirect to after the logout is performed. It must match the value preregistered in Okta during client registration.


 
state
string
An optional value that is returned as a query parameter during the redirect at the end of the flow.


 
Responses 
200
Successful logout


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/logout
Request samples 
application/x-www-form-urlencoded
id_token_hint=eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwM3VkaXR1ZGUubmV0IiwiZW1haWxf.....dmVyjoiaHR0cDovL3JhaW4ub2t0YTEuY29tOjE4MDIiLCJsb2dpbiI6ImFkbWluaXN0cmF0b3IxQGNsb3VkaXR1ZGUubmV0IiwiYXVkIjoidUFhdW5vZldrYURKeHVrQ0ZlQngiLCJpYXQiOjE0NDk2MjQwMjYsImV4cCI6MTQ0OTYyNzYyNiwiYW1yIjpbInB3ZCJdLCJqdGkiOiI0ZUFXSk9DTUIzU1g4WGVzbpJhGM91PqJwi_AylE6rp-ehamfnUAO4JL14PkemF45Pn3u_6KayXfBG3UF5-ZAlhfch1fhFT3yZFdWwzkSDc0BGygfiFyNhCezfyT454wbciSZgrA9ROeHkfPCaX7KCFO8GgQEkGRoQntFBNjluFhNLJIUkEFovEDlfuB4tv_M8BM75celdy3jkpOurg&post_logout_redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2FpostLogoutRedirectUri&state=1230000
Response samples 
application/json
{
  • "errorCode": "E0000047",
  • "errorSummary": "You exceeded the maximum number of requests. Try again in a while.",
  • "errorLink": "E0000047",
  • "errorId": "sampleQPivGUj_ND5v78vbYWW",
  • "errorCauses": [ ]
}
/oob-authenticate
Initiates Direct Authentication with an out-of-band authenticator




Note: The /oob-authenticate endpoint requires client authentication. The method is configured per client application. See Client authentication methods.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
channel_hint
required
string (Channel) 
The out-of-band channel for use with authentication. Required for all /oob-authenticate requests and any /challenge request with an out-of-band authenticator.


 Enum: "push" "sms" "voice"  
login_hint
required
string
The user sign-in information for whom authentication is being requested


 
Responses 
200
Out-of-band authentication has successfully been initiated.


400
Bad Request


401
Unauthorized


403
Forbidden


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/oob-authenticate
Request samples 
application/x-www-form-urlencoded
login_hint=testuser%40example.com&channel_hint=push
Response samples 
application/json
{
  • "oob_code": "ftOpMH6ohWMGWoH1vgrX-lNX6tnXE6JNd9",
  • "channel": "push",
  • "binding_method": "none",
  • "expires_in": 300,
  • "interval": 5
}
/par
Identity Engine
Use this operation to request the permitted communication options for the /par operation.




Note: CORS is enforced on a per-client basis. This endpoint will always return CORS headers with the current Origin.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
header Parameters
Origin
string
Indicates the origin of the client that is initiating the request


 
 Example:  example.okta.com
Responses 
204
Success


429
Too Many Requests


options/oauth2/{authorizationServerId}/v1/par
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000047",
  • "errorSummary": "You exceeded the maximum number of requests. Try again in a while.",
  • "errorLink": "E0000047",
  • "errorId": "sampleQPivGUj_ND5v78vbYWW",
  • "errorCauses": [ ]
}
/par
Identity Engine
The pushed authorization request endpoint (/par) promotes OAuth security by allowing the authorization server to authenticate the client before any user interaction happens. The increased confidence in the client's identity during the authorization process means the authorization server can refuse illegitimate requests much earlier in the process. This process prevents attempts to spoof clients or otherwise tamper with or misuse an authorization request and provides a simple way to make a confidential and integrity-protected authorization request.


The /par endpoint allows an OAuth 2.0 client to push the payload of an authorization request directly to the authorization server. The authorization server provides a request_uri value in the response that can be used as a reference to the authorization request payload data in a subsequent call to the /authorize endpoint through a user agent.


Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/json
client_id
string
Obtained during either manual client registration or through the Dynamic Client Registration API


 
code_challenge
string
A challenge for PKCE. The challenge is verified in the access token request.


 
code_challenge_method
string
Method used to derive the code challenge for PKCE


 
display
string
The display parameter to be passed to the external Identity Provider when performing social login


 
idp
string
An Okta Extension to the OpenID Specification. The ID of the Identity Provider to use if there's no Okta Session


 
idp_scope
string
An Okta Extension to the OpenID Specification. A space-delimited list of scopes to be provided to the external Identity Provider when performing social login. These scopes are used in addition to the scopes already configured for the Identity Provider.


 
login_hint
string
A username to pre-populate if prompting for authentication


 
max_age
integer
Allowable elapsed time, in seconds, since the last time the end user was actively authenticated by Okta


 
nonce
string
A value that's returned in the ID token. It's used to mitigate replay attacks. The value is required for Implicit and Hybrid flows, but optional for Auth Code flows. See OIDC Specs.


 
prompt
string
If no prompt parameter is specified, the standard behavior occurs:


    

  • If an Okta session already exists and meets the assurance requirements of the app, the user is silently authenticated. Otherwise, Okta prompts the user to authenticate.
    • 

  • If scopes are requested that require consent and consent isn't yet given by the authenticated user, Okta prompts the user to give consent.
    • 



 
redirect_uri
string
Callback location where you want the authorization code or tokens sent to. It must match the value preregistered in Okta during client registration.


 
request
string
Used to push a Request Object JWT to the authorization server


 
response_mode
string
How Okta should return the authorization response. If id_token or token is specified in the response_type, then query isn't allowed as a response mode. Defaults to fragment in implicit and hybrid flows.


The Referrer-Policy header is automatically included in the response when either the fragment or query parameter values are used. The header is set to Referrer-Policy: no-referrer.


 
response_type
string
Any combination of code, token, and id_token. The combination determines the flow.


 
scope
string
A space-delimited string of scopes requested


 
sessionToken
string
Okta one-time session token. This is an Okta extension to the OpenID specification. The sessionToken allows an API-based user sign-in flow.


 
state
string
A value returned with the token. The client app can use it to remember the state of its interaction with the end user at the time of the authentication call. It can contain alphanumeric, comma, period, underscore, and hyphen characters.


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/par
Request samples 
application/json
{
  • "client_id": "string",
  • "code_challenge": "string",
  • "code_challenge_method": "string",
  • "display": "string",
  • "idp": "string",
  • "idp_scope": "string",
  • "login_hint": "string",
  • "max_age": 0,
  • "nonce": "string",
  • "prompt": "string",
  • "redirect_uri": "string",
  • "request": "string",
  • "response_mode": "string",
  • "response_type": "string",
  • "scope": "string",
  • "sessionToken": "string",
  • "state": "string"
}
Response samples 
application/json
{
  • "request_uri": "urn:okta:Y1hIQ3ZqYjFodEZMOVJ3TUF4ZHRPZjJuNFZRV2ZWQ044MmFoX2VIT2oyNDo",
  • "expires_in": 3600
}
/revoke
CORS
The API takes an access or refresh token and revokes it. Revoked tokens are considered inactive at the introspection endpoint. A client may only revoke its own tokens. See Revoke tokens for more information.




Note: The /revoke endpoint requires client authentication. The method is configured per client application. See Client authentication methods for more information.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/json
token
required
string
An access token, refresh token, or a device secret.


 
token_type_hint
string (TokenTypeHintRevoke) 
Indicates the type of token being passed


 Enum: "access_token" "device_secret" "refresh_token"  
Responses 
200
Successful revocation. Note that revoking an invalid, expired, or revoked token is still considered a success so information isn't leaked.


400
Bad Request


401
Unauthorized


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/revoke
Request samples 
application/json
{
  • "token": "string",
  • "token_type_hint": "access_token"
}
Response samples 
application/json
{
  • "error": "invalid_request",
  • "error_description": "The `token` parameter is required."
}
/token
Use this operation to request the permitted communication options for the /token operation.




Note: CORS is enforced on a per-client basis. This endpoint will always return CORS headers with the current Origin.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
header Parameters
Origin
string
Indicates the origin of the client that is initiating the request


 
 Example:  example.okta.com
Responses 
204
Success


429
Too Many Requests


options/oauth2/{authorizationServerId}/v1/token
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000047",
  • "errorSummary": "You exceeded the maximum number of requests. Try again in a while.",
  • "errorLink": "E0000047",
  • "errorId": "sampleQPivGUj_ND5v78vbYWW",
  • "errorCauses": [ ]
}
/token
This endpoint returns access tokens, ID tokens, and refresh tokens depending on the request parameters. For password, client credentials, SAML 2.0 assertion, and refresh token flows, calling /token is the only step of the flow. For the authorization code flow, calling /token is the second step of the flow.




Note: The /token endpoint requires client authentication. The method is configured per client application. See Client authentication methods for more information.




Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Request Body schema: application/x-www-form-urlencoded
grant_type
string (GrantType) 
Determines the mechanism Okta uses to authorize the creation of the tokens.


 
code
required
string
The value is what was returned from the authorization endpoint. The code has a lifetime of 300 seconds.


 
code_verifier
string
Required if the code_challenge was specified in the original /authorize request. This value is the code verifier for PKCE. Okta uses it to recompute the code_challenge and verify if it matches the original code_challenge in the authorization request.


 
redirect_uri
string
Specifies the callback location where the authorization was sent. This value must match the redirect_uri used to generate the original authorization_code.


 
Responses 
200
Based on the scopes requested. Generally speaking, the scopes specified in a request are included in the access token in the response.


400
Bad Request


401
Unauthorized


429
Too Many Requests


post/oauth2/{authorizationServerId}/v1/token
Request samples 
application/x-www-form-urlencoded
client_id=0jrabyQWm4B9zVJPbotY&client_secret=6W7XvLCrs4ByKn7Ucwh8ygeeXRhdGFdVOTp75eOc&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2FredirectUri&code=QnowT-aeawtOJKp-MtkH%26
Response samples 
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJ2ZXIiOjEsImlzcyI6Imh0dHA6Ly9yYWluLm9rdGExLmNvbToxODAyIiwiaWF0IjoxNDQ5NjI0MDI2LCJleHAiOjE0NDk2Mjc2MjYsImp0aSI6IlVmU0lURzZCVVNfdHA3N21BTjJxIiwic2NvcGVzIjpbIm9wZW5pZCIsImVtYWlsIl0sImNsaWVudF9pZCI6InVBYXVub2ZXa2FESnh1a0NGZUJ4IiwidXNlcl9pZCI6IjAwdWlkNEJ4WHc2STZUVjRtMGczIn0.HaBu5oQxdVCIvea88HPgr2O5evqZlCT4UXH4UKhJnZ5px-ArNRqwhxXWhHJisslswjPpMkx1IgrudQIjzGYbtLFjrrg2ueiU5-YfmKuJuD6O2yPWGTsV7X6i7ABT6P-t8PRz_RNbk-U1GXWIEkNnEWbPqYDAm_Ofh7iW0Y8WDA5ez1jbtMvd-oXMvJLctRiACrTMLJQ2e5HkbUFxgXQ_rFPNHJbNSUBDLqdi2rg_ND64DLRlXRY7hupNsvWGo0gF4WEUk8IZeaLjKw8UoIs-ETEwJlAMcvkhoVVOsN5dPAaEKvbyvPC1hUGXb4uuThlwdD3ECJrtwgKqLqcWonNtiw",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "openid email offline_access",
  • "refresh_token": "a9VpZDRCeFh3Nkk2VdY",
  • "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMHVpZDRCeFh3Nkk2VFY0bTBnMyIsImVtYWlsIjoid2VibWFzdGVyQGNsb3VkaXR1ZGUubmV0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInZlciI6MSwiaXNzIjoiaHR0cDovL3JhaW4ub2t0YTEuY29tOjE4MDIiLCJsb2dpbiI6ImFkbWluaXN0cmF0b3IxQGNsb3VkaXR1ZGUubmV0IiwiYXVkIjoidUFhdW5vZldrYURKeHVrQ0ZlQngiLCJpYXQiOjE0NDk2MjQwMjYsImV4cCI6MTQ0OTYyNzYyNiwiYW1yIjpbInB3ZCJdLCJqdGkiOiI0ZUFXSk9DTUIzU1g4WGV3RGZWUiIsImF1dGhfdGltZSI6MTQ0OTYyNDAyNiwiYXRfaGFzaCI6ImNwcUtmZFFBNWVIODkxRmY1b0pyX1EifQ.Btw6bUbZhRa89DsBb8KmL9rfhku--_mbNC2pgC8yu8obJnwO12nFBepui9KzbpJhGM91PqJwi_AylE6rp-ehamfnUAO4JL14PkemF45Pn3u_6KKwxJnxcWxLvMuuisnvIs7NScKpOAab6ayZU0VL8W6XAijQmnYTtMWQfSuaaR8rYOaWHrffh3OypvDdrQuYacbkT0csxdrayXfBG3UF5-ZAlhfch1fhFT3yZFdWwzkSDc0BGygfiFyNhCezfyT454wbciSZgrA9ROeHkfPCaX7KCFO8GgQEkGRoQntFBNjluFhNLJIUkEFovEDlfuB4tv_M8BM75celdy3jkpOurg"
}
/userinfo
CORS
Returns information about the user that is the subject of the access token. Many of these claims are also included in the ID token, but calling this endpoint always returns all of the user's claims. The ID token can be configured to include a subset of the user's claims. See Scope-dependent claims for more information.


Request 
path Parameters
authorizationServerId
required
string
id of the Authorization Server


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


429
Too Many Requests


get/oauth2/{authorizationServerId}/v1/userinfo
Request samples 
Response samples 
application/json
{
  • "sub": "00uid4BxXw6I6TV4m0g3",
  • "name": "John Doe",
  • "nickname": "Jimmy",
  • "given_name": "John",
  • "middle_name": "James",
  • "family_name": "Doe",
  • "profile": "https://example.com/john.doe",
  • "zoneinfo": "America/Los_Angeles",
  • "locale": "en-US",
  • "updated_at": 1311280970,
  • "email": "john.doe@example.com",
  • "email_verified": true,
  • "address": {
    • "street_address": "123 Hollywood Blvd.",
    • "locality": "Los Angeles",
    • "region": "CA",
    • "postal_code": "90210",
    • "country": "US"
    },
  • "phone_number": "+1 (425) 555-1212"
}