/authorize

Request

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

Query

acr_valuesstring(AcrValue)

You can include an optional parameter in the authentication request. This parameter increases the level of user assurance.

Note: You can also 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"

idp_scopestring

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.

idpstring

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

interclient_tokenstring

A token used to SSO into the client app

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 you don't specify the prompt parameter, 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.

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"

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

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.

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 for information on how to build a JWT.

Okta supports the HMAC, RSA and ECDSA signature algorithms. HMAC signatures require that the client have a token_endpoint_auth_method that uses a client_secret. RSA and ECDSA signatures require that the client registers a public key.
Okta recommends that you don't duplicate any request parameters in the JWT and the query URI. 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.

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 that is 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.

GET

/oauth2/v1/authorize

curl -i -X GET \
  'https://okta-subdomain.pixtulate.com/oauth2/v1/authorize?acr_values=phr&client_id=string&code_challenge=string&code_challenge_method=S256&display=string&enroll_amr_values=duo&idp_scope=string&idp=string&interclient_token=string&login_hint=string&max_age=0&nonce=string&prompt=consent&redirect_uri=string&response_type=code&response_mode=form_post&request_uri=string&request=string&scope=string&sessionToken=string&state=string'

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": []
}