OAuth App – Authorization Code & PKCE Setup

PKCE Overview

Proof Key for Code Exchange (PKCE) is an extension of the OAuth 2.0 Authorization Code flow that enhances security for public or mobile clients that cannot safely store a client secret. It adds a verification step between the authorization request and token exchange to prevent intercepted authorization codes from being reused by malicious actors. You should use PKCE if your application is a mobile app, single-page app (SPA), or any client that cannot securely store a client secret. If your application is a traditional server-side (confidential) client, you can continue using the standard Authorization Code flow.

PKCE (RFC 7636) is also available to developers as an extension of the authorization code flow. To enable it, toggle PKCE in the App details page.

5d438b48f6491e173c4f3f92e9c350000b1ff8497477459e6db264edc8026016 pkce gif

Once PKCE is enabled, the application can only use the PKCE workflow. If PKCE parameters are not provided, the authorization code flow will fail. To switch back the toggle, the application should have no active keys.

Once your app parameters are set, you can implement the authorization code flow. To request access, create a Consent link that redirects the user.

If you’re familiar with the Client Credentials workflow, you might notice that the Generate Consent URL button is not present in the partner portal for the authorization code workflow. This is because, with the authorization code method, you need to provide a redirect URI specific to your organization. Therefore, these URLs must be configured directly within your workflow.

If the redirect URI is not declared in the application, the redirection will be blocked.

If you have PKCE enabled, then the consent URL will require additional parameters:

URL

https://consent.criteo.com/request?response_type=code
&client_id={client_id}
&redirect_uri={redirect_uri}
&state={state}
&code_challenge={code_challenge}
&code_challenge_method={code_challenge_method}

Parameter	Required	Description
`response_type=code`	Yes	Indicates that an authorization code is expected as outcome.
`client_id`	Yes	Your public key from the app credentials section.
`redirect_uri`	Yes	The URL to redirect the user after consent. Must match the configured URI.
`state`	No	Optional string to prevent Cross-Site Request Forgery attacks.
`code_challenge`	Yes when PKCE is enabled	A challenge derived from the `code_verifier` that is sent in the authorization request, to be verified against later.
`code_challenge_method`	No	The method used to derive `code_challenge`. `plain`: no transformation (not recommended) `S256`: recommended & secure (hash + base64url) — default when no method is provided

Step 2. Exchanging the Authorization Code for an Access Token

You can find more details about the OAuth endpoint in our API Reference.

If you have PKCE enabled, your token request must include code_verifier. The client_secret is optional — the code_verifier authenticates the request in its place. If you do send a client_secret, it must be valid.

Example Request

curl -L 'https://api.criteo.com/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=<MY_CLIENT_ID>' \
-d 'redirect_uri=<MY_URI>' \
-d 'code=<MY_CODE>' \
-d 'grant_type=authorization_code' \
-d 'code_verifier=<MY_CODE_VERIFIER>'

Example Response (Success)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

Parameters

Parameter	Required	Description
`grant_type=authorization_code`	Yes	Indicates that you are providing an authorization code.
`code`	Yes	Authorization code returned during redirection.
`redirect_uri`	Yes	Must match the `redirect_uri` used for the authorization request.
`client_id`	Yes	Your public key from the app credentials.
`client_secret`	No	Your secret key. Optional for PKCE applications — the `code_verifier` authenticates the request. If provided, it must be valid. For confidential (non-PKCE) clients, this is required and is shown only once when creating credentials.
`code_verifier`	Yes	A high-entropy random string created by the client (usually 43–128 characters).

Step 3. Using the Refresh Token

PKCE refresh tokens are short-lived and the session has a hard cap. The table below summarizes the differences from a standard app.

	Standard app	PKCE app
`client_secret` on refresh	Required	Optional (validated if provided)
Refresh token lifetime	180 days	3 hours
Maximum session length	None	24 hours from the initial code exchange
`client_id` must match the token’s client	Not enforced	Enforced (`invalid_grant` if mismatched)
Tokens issued on refresh	Standard	Still PKCE; the 24-hour start time carries over

How the 24-hour cap works: each refresh returns a new refresh token, but the session start time is carried over and never resets. Each new refresh token’s lifetime is the smaller of 3 hours and the time remaining in the 24-hour session. Once the 24-hour limit is reached, the refresh fails with invalid_grant and the user must re-authorize through the full authorization code and PKCE flow. Always store the latest refresh token — previous ones are invalidated on each refresh.

Example Request

curl -X POST https://api.criteo.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}"

Parameters

Parameter	Required	Description
`grant_type=refresh_token`	Yes	Indicates that you are providing a refresh token.
`refresh_token`	Yes	The refresh token returned when issuing the access token. Always use the most recently issued one.
`client_id`	Yes	Your public key from the app credentials section. Must match the client the token was issued to.
`client_secret`	No	Optional for PKCE applications. If provided, it must be valid. Required for confidential (non-PKCE) clients.

The response is the same shape as the initial token response.

Error Codes

Code	HTTP status	When it occurs
`invalid_client`	`400`	Wrong `client_secret`, or `client_secret` is missing for a non-PKCE app.
`invalid_grant`	`400`	Expired, invalid, or already-used refresh token; `client_id` mismatch on a PKCE refresh; or a PKCE session past its 24-hour limit.
`invalid_request`	`400`	Missing `client_id`.

Introduction

Getting Started

API Troubleshooting

Concepts

Resources

OAuth App – Authorization Code & PKCE Setup

PKCE Overview

Step 2. Exchanging the Authorization Code for an Access Token

Example Request

Example Response (Success)

Parameters

Step 3. Using the Refresh Token

Example Request

Parameters

Error Codes

​PKCE Overview

​Step 1. Consent URL

​Consent URL

​Authorization Code vs. Client Credentials Consent URLs

​Step 2. Exchanging the Authorization Code for an Access Token

​Example Request

​Example Response (Success)

​Parameters

​Step 3. Using the Refresh Token

​Example Request

​Parameters

​Error Codes

PKCE Overview

Step 1. Consent URL

Consent URL

Authorization Code vs. Client Credentials Consent URLs

Step 2. Exchanging the Authorization Code for an Access Token

Example Request

Example Response (Success)

Parameters

Step 3. Using the Refresh Token

Example Request

Parameters

Error Codes