--- title: OAuth 2.0 endpoint parameters description: Requests to OAuth 2.0 endpoints use the following parameters. component: pingoneaic page_id: pingoneaic:am-oauth2:oauth2-parameters canonical_url: https://docs.pingidentity.com/pingoneaic/am-oauth2/oauth2-parameters.html keywords: ["OAuth 2.0", "Endpoints", "Properties"] page_aliases: ["oauth2-guide:oauth2-parameters.adoc"] section_ids: acr-values: acr_values actor-token: actor_token actor-token-type: actor_token_type auth-chain: auth_chain authorization_details: authorization_details claims: claims client-assertion: client_assertion client-assertion-type: client_assertion_type client-id: client_id client-secret: client_secret cnf-key: cnf_key code-challenge: code_challenge code-challenge-method: code_challenge_method code-verifier: code_verifier csrf: csrf decision: decision grant-type: grant_type id-token-hint: id_token_hint login-hint: login_hint nonce: nonce prompt: prompt redirect-uri: redirect_uri response-mode: response_mode response-type: response_type the-request-parameter: request general_validation_rules: General validation rules jar_validation_rules: JAR validation rules oidc_validation_rules: OIDC validation rules par_validation_rules: PAR validation rules example-request-object: Example request object request-uri: request_uri requested-token-type: requested_token_type save-consent: save_consent scope: scope service: service state: state subject-token: subject_token subject-token-type: subject_token_type ui-locales: ui_locales --- # OAuth 2.0 endpoint parameters Requests to OAuth 2.0 endpoints use the following parameters. Refer to the individual OAuth 2.0 endpoint pages to determine the required and optional parameters for each endpoint. ## `acr_values` The OpenID Connect authentication context class reference values. [OpenID Connect (OIDC) flows](https://openid.net/specs/openid-connect-core-1_0.html) only. Authentication context class reference values communicate acceptable Levels of Assurance (LoAs) users must satisfy when authenticating to the OpenID provider. For details, refer to [Authentication requirements](../am-oidc1/oidc-authentication-requirements.html). ## `actor_token` The token representing a delegate acting on behalf of another identity in [Token exchange](token-exchange.html). ## `actor_token_type` The type of the actor token: * `urn:ietf:params:oauth:token-type:access_token` * `urn:ietf:params:oauth:token-type:id_token` ## `auth_chain` A string naming the journey to authenticate the resource owner for [Resource owner password credentials grant](oauth2-ropc-grant.html). The journey must permit username-password authentication without UI interaction. Otherwise, the request results in an HTTP 500 Internal Server Error. Default: The default authentication journey for the realm. ## `authorization_details` A valid JSON array containing fine-grained authorization requirements, as specified in [RFC 9396: OAuth 2.0 Rich Authorization Requests](https://www.rfc-editor.org/rfc/rfc9396.html). Each authorization detail object in the array must contain a non-blank `type` string. For example: ```json "authorization_details": [{ "type": "account_information", "actions": [ "list_accounts", "read_balances", "read_transactions" ], "locations": [ "https://example.com/accounts" ] }], ``` If the `type` is missing or blank, Advanced Identity Cloud returns an `invalid_authorization_details` error. ## `claims` A JSON object containing the user attributes to return in the ID token. [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. ## `client_assertion` A signed JSON Web Token (JWT) to use as client credentials for [JWT profile](client-auth-jwt.html) authentication. ## `client_assertion_type` The type of assertion for [JWT profile](client-auth-jwt.html) authentication. Set `client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer`. ## `client_id` A unique string identifier for the application making the request. For a [pushed authorization request](oauth2-authz-grant-par.html) or a [JWT-secured authorization request](https://www.rfc-editor.org/rfc/rfc9101.html) (RFC 9101), this value must match the `client_id` claim in the `request` object. ## `client_secret` A string password credential for the confidential client application making the request. Use this parameter for client authentication with [Form parameters (HTTP POST)](client-auth-form.html). Do not use with the `cnf_key` parameter. ## `cnf_key` A base64-encoded JSON Web Key (JWK) for [JWK-based proof-of-possession](oauth2-PoP-JWK.html). Do not use with the `client_secret` parameter. ## `code_challenge` A generated code verifier string for RFC 7636 [Proof Key for Code Exchange](https://www.rfc-editor.org/rfc/rfc7636) (PKCE). For details, refer to [Generate a code verifier and a code challenge](oauth2-authz-grant-pkce.html#proc-auth-code-generate-pkce). ## `code_challenge_method` A string specifying the method to derive the PKCE code challenge: * `plain` (default; plaintext code challenge ) * `S256` (recommended; hashed code challenge) ## `code_verifier` A random string correlating a PKCE authorization request with the token request. ## `csrf` The SSO token string linking the request to user session to protect against Cross-Site Request Forgery (CSRF) attacks. This parameter duplicates the value of the session cookie, the resource owner's SSO token. Built-in consent pages include this parameter once the resource owner has authenticated, and send it with the resource owner's consent. Custom consent pages and flows that do not use a browser must set this parameter explicitly unless you use a [Remote consent service](oauth2-remote-consent.html). For an example, refer to the [Authorization code grant](oauth2-authz-grant.html). ## `decision` A string indicating whether the resource owner consents to the requested access: * `allow` to grant consent * Any other value denies consent ## `grant_type` A string specifying the type of grant to acquire an access token: * `authorization_code` For [authorization code grants](oauth2-authz-grant.html). * `client_credentials` For the [Client credentials grant](oauth2-client-cred-grant.html). * `password` For the [Resource owner password credentials grant](oauth2-ropc-grant.html). * `refresh_token` To [refresh an access token](oauth2-refresh-tokens.html). * `urn:ietf:params:oauth:grant-type:device_code` For the [Device authorization grant](oauth2-device-flow.html). Advanced Identity Cloud also supports the earlier `http://oauth.net/grant_type/device/1.0` specification. * `urn:ietf:params:oauth:grant-type:saml2-bearer` For the [SAML 2.0 profile for authorization](oauth2-saml2-bearer-grant.html). * `urn:ietf:params:oauth:grant-type:jwt-bearer` For the [JWT profile for authorization](oauth2-jwt-bearer-grant.html). * `urn:ietf:params:oauth:grant-type:token-exchange` For the [Token exchange](token-exchange.html). * `urn:openid:params:grant-type:ciba` For the [Backchannel request grant](../am-oidc1/openid-connect-backchannel-request-flow.html). ## `id_token_hint` A previously issued ID token passed as a hint about the end user's session with the client. [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. Set the `response_type` and `prompt` parameters to `none` when using this parameter. For details, refer to [Session Management Draft 10](../am-oidc1/session-management.html#session_management_state). ## `login_hint` A string specifying the ID used to log in. [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. The ID depends on the authentication journey. When provided as part of the OpenID Connect authentication request, an `HttpOnly` cookie (only sent over HTTPS) named `oidcLoginHint` gets the value of `login_hint`. For details, refer to [GSMA Mobile Connect](../am-oidc1/oidc-mobile-connect.html). ## `nonce` A string linking the client session with the ID token to mitigate against replay attacks. [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. ## `prompt` A space-separated, case-sensitive list of ASCII strings that indicates whether to prompt the end user for authentication and consent. [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. * `consent` Prompt the end user for consent even if a consent response was previously saved. * `login` Prompts the end user to authenticate using the journey specified with the [`service`](#service) parameter. When the user re-authenticates, Advanced Identity Cloud destroys the original session and creates a new one for the new journey. Default: The default journey for the realm. * `none` Do not display authentication or consent pages. Use this only when you set `id_token_hint` and `response_type=none`. ## `redirect_uri` The URI to return the resource owner to after authorization is complete. Default: A value from the client profile Sign-in URLs setting in the Advanced Identity Cloud admin console. ## `response_mode` A string specifying the mechanism for returning response parameters: * `form_post` Return a self-submitting form that contains the code instead of redirecting to the redirect URL with the code as a string parameter. For details, refer to [OAuth 2.0 Form Post Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html). * `fragment` Return parameters encoded in the URL fragment; default when `response_type=token`. * `fragment.jwt` Return a JWT in a fragment. * `jwt` Return parameters in a JWT; in a query string for the `code` response type, or appended to the fragment for the `token` response type. A JWT-secured authorization response (JARM) returns authorization response parameters in a signed, optionally encrypted, JWT. Configure the algorithms to secure the JWT in the Advanced Identity Cloud admin console under Applications > *Client ID* > Sign On > General Settings > Show advanced settings > Signing and Encryption. In addition to claims specific to the response type, such as `code` or `access_token`, the JWT contains these mandatory claims: * `iss`: the URL of the issuer—​the authorization server that generated the response * `aud`: the audience—​the client ID intended as the response recipient * `exp`: the expiration of the JWT—​10 minutes is the recommended maximum On error, the JWT contains: * An `error` string * A `state` string if specified by the client * An error description For details, refer to [JWT-Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html). * `query` Return parameters encoded in the query string; default when `response_type=code`. * `query.jwt` Return a JWT in a query parameter. Do *not* use this with `id_token` or `token` response types unless the response JWT is encrypted. For details, refer to [Response Modes](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes). Advanced Identity Cloud publishes supported response modes as `response_modes_supported` through the [/oauth2/.well-known/openid-configuration](../am-oidc1/rest-api-oidc-discovery-configuration.html) endpoint. ## `response_type` A string specifying the response expected from the authorization server: * `code` An authorization code for an authorization code grant * `code id_token` An authorization code and an ID token for a hybrid grant * `code token` An authorization code and an access token for a hybrid grant * `code token id_token` An authorization code, an access token, and an ID token for a hybrid grant * `id_token` An ID token for an implicit grant * `none` Do not issue any token or code in the response; for use with [`id_token_hint`](#id-token-hint) only * `token` An access token for an implicit grant * `token id_token` An access token and an ID token for an implicit grant ## `request` A base64url-encoded JWT whose claims are required for an [OIDC flow](https://openid.net/specs/openid-connect-core-1_0.html), a [JWT-secured authorization (JAR) request](https://www.rfc-editor.org/rfc/rfc9101.html) (RFC 9101), or a [pushed authorization request (PAR)](https://www.rfc-editor.org/info/rfc9126) (RFC 9126). This JWT is called the *request object*. Advanced Identity Cloud validates request objects according to: * The type of request * The OAuth 2.0 provider configuration (specifically, the [Request Object Processing Specification](../am-reference/services-configuration.html#config-request-object-proc-spec) setting) * The value of the ESV named `esv-oauth2-provider-request-object-processing-enforced`, if set The validation rules apply whether you pass the request object by value with the `request` parameter or as a reference with the `request_uri` parameter: > **Collapse: How Advanced Identity Cloud determines which rules to apply** > > | Input | | | | Behavior | > | --------------------- | --------------- | ---------------- | ---------------- | ------------ | > | Specification value 1 | `enforced` ESV2 | OIDC parameters3 | `/par` endpoint4 | Rule applied | > | OIDC | `false` | Yes | No | OIDC | > | OIDC | `false` | No | No | JAR | > | OIDC | `true` | Yes | No | OIDC | > | OIDC | `true` | No | No | OIDC | > | JAR | `false` | Yes | No | JAR | > | JAR | `false` | No | No | JAR | > | JAR | `true` | Yes | No | JAR | > | JAR | `true` | No | No | JAR | > | OIDC | `false` | Yes | Yes | PAR | > | OIDC | `false` | No | Yes | PAR | > | OIDC | `true` | Yes | Yes | PAR | > | OIDC | `true` | No | Yes | PAR | > | JAR | `false` | Yes | Yes | PAR | > | JAR | `false` | No | Yes | PAR | > | JAR | `true` | Yes | Yes | PAR | > | JAR | `true` | No | Yes | PAR | > > 1 Value of the Request Object Processing Specification setting > > 2 The value of the ESV named `esv-oauth2-provider-request-object-processing-enforced` > > 3 Request contains OIDC parameters > > 4 Request is sent to [/oauth2/par](oauth2-par-endpoint.html) endpoint ### General validation rules These rules apply for all request objects: * The request object must include a `client_id` that matches the [`client_id`](#client-id) parameter of the request. * If the request object is signed or encrypted, you *must* include the `iss` and `aud` parameters, as shown in the [Example request object](#example-request-object). For the public keys to encrypt a request object JWT, send a request to the realm's [/oauth2/connect/jwk\_uri](../am-oidc1/managing-jwk_uri.html) endpoint. * The `exp` (expiration time) and `nbf` (not before) claims set the timeframe during which the request object is valid. If the OAuth 2.0 provider settings declare them mandatory, you *must* include the `exp` and `nbf` claims. If specified, validation uses these claims even when the OAuth 2.0 provider settings don't require them. Read the [OAuth 2.0 provider](../am-reference/services-configuration.html#realm-oauth-oidc) configuration reference to make sure the values meet the requirements of the [Financial-grade API (FAPI)](https://openid.net/specs/openid-financial-api-part-2-1_0-final.html#authorization-server) security profile. * Compressed JWTs mustn't be larger than 32 KiB (32768 bytes) when uncompressed. ### JAR validation rules * The request object is signed. (It *may* also be encrypted.) * The authorization request uses only the request object claims, even when the request specifies the same claims in query string parameters. ### OIDC validation rules * The request object doesn't require signing or encryption. * You *may* send query string parameters and a request object in the same request. You can keep sensitive information protected in the request object, and keep parameters that change frequently, such as `nonce` and `state`, visible and mutable across calls. The claims in the request object supersede the query string parameters. * You *must* include the `response_type` as a query string parameter, even if you include it in the request object. The values in the request object must match those passed as query string parameters. * If the request object contains the `openid` scope, you *must* include the `openid` scope in the request syntax. The `scope` claim *may* differ from the `scope` query string parameter. Use this to protect application-related scopes in the request object, but process the request as part of an OpenID Connect flow. ### PAR validation rules * The request object *must* be signed. It *may* be encrypted. * You *must* include claims for all other parameters required for the successful completion of the grant flow. For example, include the `code_challenge` for an [Authorization code grant with PKCE](oauth2-authz-grant-pkce.html) flow. * When you include the request object, omit all other parameters except to authenticate the client. The request object *must* include claims for all other request details. Otherwise, the response is an `Invalid parameter scope` error. ### Example request object The following example JWT request object includes OIDC claims and `iss`, `aud`, `nbf`, and `exp` claims. Advanced Identity Cloud ignores keys specified in JWT headers, such as `jku` and `jwe`: ```json { "client_id": "myClient", "iss": "myClient", "aud": "https:///am/oauth2/realms/root/realms/alpha", "nbf": 1675351332, "exp": 1675351692, "redirect_uri": "https://www.example.com:8443", "scope": "openid profile", "claims": { "id_token": { "acr": { "essential": true, "values": ["example_journey1", "example_journey2"] } } } } ``` To pass the request object by value, specify the encoded JWT as shown in this example OIDC call: ``` https:///am/oauth2/realms/root/authorize? \ &request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3... \ &client_id=myClient \ &scope=openid profile \ &response_type=code%20id_token \ &nonce=abc123 \ &state=123abc ``` ## `request_uri` A reference to [JWT request object(s)](#the-request-parameter). * For [PAR flows](oauth2-authz-grant-par.html), this references the data at the time of the PAR request. The authorization request fails if the request URI has expired. * For [OIDC flows](../am-oidc1/oidc-implementing-flows.html) and [JAR](https://www.rfc-editor.org/rfc/rfc9101.html) requests, this references an array of URIs to retrieve request objects whose claims constitute the request parameters. You must pre-register the URIs in the client profile. In the Advanced Identity Cloud admin console, go to Applications > *Client ID* > Sign On > Show advanced settings > Authentication > Request URIs. Each request URI must not exceed 512 ASCII characters and must use either HTTP or HTTPS; for example, `https://www.example.com:8443/JTWs/myJWT`. Advanced Identity Cloud caches the request objects to avoid requesting them too often. To force Advanced Identity Cloud to flush the cache, add a unique fragment to the `request_uri` parameter; for example, `?request_uri=https://www.example.com:8443/JTWs/myJWT#foo`. * The [PAR](https://www.rfc-editor.org/rfc/rfc9126.html) and [JAR](https://www.rfc-editor.org/rfc/rfc9101.html#section-5.2) specifications indicate the following: * The authorization server should ignore authorize parameters outside the `request_uri`. * When sending a JWT-Secured Authorization Request (JAR), the `request_uri` *must* be an `https` URI. To enforce this behavior in Advanced Identity Cloud, [create an ESV variable](../tenants/esvs.html#variables) named `esv.oauth2.request.object.restrictions.enforced` and set its value to `true`. ## `requested_token_type` The type of token requested for [Token exchange](token-exchange.html): * `urn:ietf:params:oauth:token-type:access_token` (default) * `urn:ietf:params:oauth:token-type:id_token` ## `save_consent` `save_consent=on` means save the scopes the resource owner's consented to. Saving consent requires prior configuration. For details, refer to [Store consent decisions](oauth2-manage-consent.html#store-consent-decisions). ## `scope` A string specifying the permissions the client application requests from the resource owner. Separate scopes with spaces. Some grants, such as the authorization code grant, do not call the token endpoint with the scope. The scope is defined in the authorization code. For details, refer to the documentation for the flow under [OAuth 2.0 grant flows](oauth2-implementing-flows.html). Default: The default scopes specified in the client profile or the OAuth 2.0 provider configuration. ## `service` A string naming the journey to authenticate the resource owner. Default: The default authentication journey for the realm. For details, refer to [Authentication parameters](../am-authentication/authn-from-browser.html#authn-from-browser-parameters). ## `state` A string value to maintain state between the request and the callback. During authentication, the client sends this parameter to the authorization server. The authorization server sends it back unchanged in the response. Use the value to ensure the response belongs to the user who initiated the requests. This mitigates against CSRF attacks. Use a base64-encoded string of data that is unique to a user and to this request. ## `subject_token` The original token to exchange in [Token exchange](token-exchange.html). ## `subject_token_type` The type of the subject token: * `urn:ietf:params:oauth:token-type:access_token` * `urn:ietf:params:oauth:token-type:id_token` ## `ui_locales` A string indicating the end user's preferred languages for the user interface. [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. The `ui_locales` parameter is a space-separated list ordered by preference; for example, `en fr-CA fr`.