/authorize

Request

This is a starting point for browser-based OpenID Connect flows such as the implicit and authorization code flows. This endpoint method behaves the same as GET /oauth2/{authorizationServerId}/v1/authorize, except that all parameters are specified in the request body and submitted through the form post. No query parameters are allowed.

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 app, or displaying an error.

Path

authorizationServerIdstringrequired

id of the authorization server

Bodyapplication/x-www-form-urlencoded

acr_valuesstring(AcrValue)

An optional parameter that you can include in the authentication request. This parameter increases the level of user assurance.

Note: You can provide multiple space-delimited values. The authorization server chooses one and reflects the chosen value in any resulting tokens.

Enum Value	Description
phr	Phishing-Resistant. Requires users to provide possession factors that cryptographically verify the sign-in server (the origin). Currently, only the Passkey (FIDO2 WebAuthn) authenticator 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_idstringrequired

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_challengestring

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

code_challenge_methodstring(CodeChallengeMethod)

Method used to derive the code challenge for PKCE.

Value:"S256"

displaystring

The display parameter to be passed to the external identity provider when performing social login

enroll_amr_valuesstring(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"

idpstring

An Okta extension to the OpenID specification. The ID of the identity provider to use if there's no Okta session.

idp_scopestring

An Okta extension to the OpenID specification. A space-delimited list of scopes you want to provide 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_hintstring

A username to pre-populate if prompting for authentication

max_ageinteger

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

noncestring

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.

promptstring(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 Value	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_uristringrequired

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

requeststring

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.
You can't encrypt the JWT.

Note: See Build a JWT for client authentication.

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. 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. 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. Okta rejects the JWT if the jti claim is present and it has already been processed.

request_uristring

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.

response_modestring(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 Value 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 app 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

response_typestring(ResponseTypesSupported)required

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"

scopestringrequired

A space-delimited string of scopes requested

sessionTokenstring

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

statestringrequired

A value to be 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.

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.

resourceArray of strings, (uri)

An absolute URI that identifies the target resource server that requests the access token. Use this parameter to restrict the token to a specific resource server or servers. Repeat the parameter to request a token that's valid for multiple resource servers. When this parameter is included in a request, the issued token's aud claim is bound to the specified resource(s).

Note: Multiple audiences for custom authorization servers is a self-service Early Access (EA) feature. See Manage Early Access and Beta features to enable the feature.

POST

/oauth2/{authorizationServerId}/v1/authorize

curl -i -X POST \
  'https://okta-subdomain.pixtulate.com/oauth2/{authorizationServerId}/v1/authorize' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d acr_values=string \
  -d client_id=string \
  -d code_challenge=string \
  -d code_challenge_method=string \
  -d display=string \
  -d enroll_amr_values=string \
  -d idp=string \
  -d idp_scope=string \
  -d login_hint=string \
  -d max_age=0 \
  -d nonce=string \
  -d prompt=string \
  -d redirect_uri=string \
  -d request=string \
  -d request_uri=string \
  -d response_mode=string \
  -d response_type=string \
  -d scope=string \
  -d sessionToken=string \
  -d state=string \
  -d 'resource=["http://example.com"]'

Responses

Too Many Requests

Bodyapplication/json

errorCausesArray of objects

errorCodestring

An Okta code for this type of error

errorIdstring

A unique identifier for this error. Okta Support can use this to help with troubleshooting.

errorLinkstring

An Okta code for this type of error

errorSummarystring

A short description of what caused this error. Sometimes this contains dynamically-generated information about your specific error.

Response

{
  "errorCode": "E0000047",
  "errorSummary": "You exceeded the maximum number of requests. Try again in a while.",
  "errorLink": "E0000047",
  "errorId": "sampleQPivGUj_ND5v78vbYWW",
  "errorCauses": []
}