The authorization request flow depends on the grant type you have selected for the application. The grant type can be an authorization code, implicit, or a hybrid (both code and implicit).

Authorization code grant type

If the grant type is authorization_code, PingOne returns an authorization code in the response to the application’s authorization request. The Location HTTP header returned by the /as/resume endpoint contains the authorization code. The authorization code returned in the resume endpoint response is used by the /as/token endpoint to get an ID token, an access token, or both.

PingOne supports GET and POST HTTP methods for initiating the authorize request.

Authorization code authorize request using GET

Step 1: Send an authorize request to the PingOne authorization server using GET.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri=https://example.com&scope=openid'

The request requires the following properties in the request URL:

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (authorization_code).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

The Location HTTP header returned by the resume endpoint contains the code. Note that the PingOne API uses session token cookies to establish the user’s authentication session and maintain the session throughout the workflow, allowing the flow to redirect back to the authorization server to get the token.

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri=https://www.example.com'

The request requires the following properties in the request URL:

The token endpoint response returns the access token, ID token, or both. For information about the authorization code token request based on the application’s tokenEndpointAuthMethod, see Token.

Authorization code authorize request using POST

The authorize request using POST is essentially the same as GET. The POST request accepts all the same parameters as the GET request. For the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'response_type=code' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'redirect_uri=https://example.com' \
--data-urlencode 'scope=openid'

The request requires the following properties in the request URL:

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (authorization_code).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri=https://www.example.com'

Implicit grant type

For an implicit grant type, the response to the authorization request is an id_token, a token (access token), or both, depending on the value of the response_type parameter in the authorization request. The implicit workflow does not need to call the token endpoint. The response from the resume endpoint includes the token (or tokens) in the Location header.

PingOne supports GET and POST HTTP methods for initiating the implicit authorize request.

Implicit authorize request using GET

Step 1: Send an authorize request to the PingOne authorization server using GET.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=token id_token&client_id={{appID}}&redirect_uri=https://example.com&scope=openid'

The request requires the following properties in the request URL:

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (implicit).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

The Location HTTP header returned by the resume endpoint contains the token, ID token, or both. Note that the PingOne API uses session token cookies to establish the user’s authentication session and maintain the session throughout the workflow, allowing the flow to redirect back to the authorization server to get the token.

Implicit authorize request using POST

The POST request accepts all the same parameters as the GET request. For the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying theContent-Type: application/x-www-form-urlencoded` request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'response_type=token id_token' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'redirect_uri=https://example.com' \
--data-urlencode 'scope=openid'

The request requires the following properties in the request URL:

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (implicit).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

Hybrid grant type

In a hybrid authorize flow, an authorization code is returned from the authorization endpoint, some tokens are returned from the authorization endpoint, and others are returned from the token endpoint. The authorization endpoint’s response_type property specifies the code type and it also specifies id_token, or token, or both. An authorization code (specified by the code response type) is always returned in a hybrid flow.

PingOne supports GET and POST HTTP methods for initiating the authorize request.

Hybrid authorize request using GET

Step 1: Send an authorize request to the PingOne authorization server using GET.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=code token&client_id={{appID}}&redirect_uri=https://example.com&scope=openid'

The request requires the following properties in the request URL:

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (hybrid).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

The Location HTTP header returned by the resume endpoint contains the code. In addition, the Location header for a hybrid authorization flow also returns the token or ID token (or both) if specified in the response_type property.

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri=https://www.example.com'

The request requires the following properties in the request URL:

The token endpoint exchanges the code for an access token, ID token, or both. For information about the authorization code token request based on the application’s tokenEndpointAuthMethod, see Token.

Hybrid authorize request using POST

The authorize request using POST is essentially the same as GET. The POST request accepts all the same parameters as the GET request. For the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'response_type=code id_token' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'redirect_uri=https://example.com' \
--data-urlencode 'scope=openid'

The request requires the following properties in the request URL:

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (hybrid).

Step 2: After the sign-on flow completes, call the resume endpoint. The Location HTTP header returned by the resume endpoint contains the code. In addition, the Location header for a hybrid authorization flow also returns the token or ID token (or both) if specified in the response_type property.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri=https://www.example.com'

PKCE parameters

For added security, you can also include Proof Key for Code Exchange (PKCE) parameters in the authorization request for the code and hybrid grant types. PKCE for OAuth uses either plain text or a cryptographic hash of a random string that is included in the authorization request (code_challenge) along with the encoding method used (code_challenge_method). When the authorization code is issued in the response, the original plain text or random string (code_verifier) is included in the token request.

Step 1: Send an authorize request to the PingOne authorization server.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri=https://www.example.com&scope=openid&code_challenge={{codeChallenge}}&code_challenge_method=S256'

The request requires the following properties in the request URL:

For more information about the PKCE query parameters that can be set on the request, see Authorize (authorization_code).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

The Location HTTP header returned by the resume endpoint contains the code. Note that the PingOne API uses session token cookies to establish the user’s authentication session and maintain the session throughout the workflow, allowing the flow to redirect back to the authorization server to get the token.

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'code_verifier={{codeVerifier}}'

The request requires the following properties in the request URL:

The token request transforms the code_verifier property value using the code_challenge_method specified in the authorize request. If the transformed code_verifier value is equal to the code_challenge value submitted in the authorize request, then the authorization server issues the token.

For information about additional parameters supported by the authorization code token request, see Token.