The authentication process

An application gets a token for a user in four steps (the OAuth 2.0 authorization code grant).

1. Send the user to the authorize page

https://www.example.com/oauth/authorize?client_id=<client id>&redirect_uri=<endpoint URI>&response_type=code&state=<random>
    (with PKCE also) &code_challenge=<challenge>&code_challenge_method=S256

The user signs in (with the second step, if the account has one) and allows the application. The user needs the policy oauth/authorize; without it the site redirects back with error=access_denied.

2. Receive the code

The site redirects to the endpoint URI with code=<code> and the unchanged state. The application checks that state is the one it sent.

3. Exchange the code for a token

curl -s https://www.example.com/api/auth/v1/oauth/token \
     -d grant_type=authorization_code -d client_id='<client id>' -d client_secret='<client secret>' \
     -d code='<code>' -d redirect_uri='<endpoint URI>'
# with PKCE also: -d code_verifier='<verifier>'; a public client sends no client_secret

The answer has the access token, its lifetime and a refresh token.

4. Call the API

curl -s -H "Authorization: Bearer <access token>" https://www.example.com/api/ezp/v2/content/node/2

The token can also be sent as Authorization: OAuth <token>, or as the oauth_token field of a POST form (unless AllowTokenInBody=disabled); as a query parameter only with AllowTokenInQuery=enabled, which is off by default.

Refreshing

When the access token has expired, the application asks for a new one with grant_type=refresh_token and refresh_token=<refresh token>, with its client identifier and secret.

Errors

• A code is used once; a wrong code_verifier uses it up (invalid_grant).
• A code or refresh token is accepted only from the client it was issued to.
• Tokens, codes and refresh tokens stop working when the user is disabled or locked.

Related pages

• REST API v1 and v2, section 3.1
• PKCE and state