---
updatedAt: 2026-05-29T12:29:09.000Z
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# Token exchange

## Tokens

The token exchange flow is a crucial feature of OAuth 2.0, allowing clients to maintain continuous access to resources without requiring users to re-authenticate repeatedly. The access token response, contains the following details

```json
{
   "access_token":"",
   "expires_in":259200,
   "refresh_expires_in":15551995,
   "refresh_token":"",
   "token_type":"Bearer",
   "not-before-policy":1683537926,
   "scope":"offline_access core_data exports email profile"
}
```

<br />

* **access\_token:** The new access token used to access protected resources.
* **expires\_in:** The duration in seconds until the access token expires (e.g., 259200 seconds, which is approximately 3 days).
* **refresh\_expires\_in:** The duration in seconds until the refresh token expires (e.g., 15,551,995 seconds, which is approximately 180 days).
* **refresh\_token:** A token used to obtain a new access token when the current one expires.
* **token\_type:** The type of the token issued (e.g., “Bearer”).
* **not-before-policy:** The timestamp indicating when the token becomes valid.
* **scope:** The scope of access granted by the token (Read more about: [Token Scopes](https://developer.candis.io/docs/access-token-scopes))

> 📘 Refresh token expiration
>
> The `refresh_expires_in` value (approximately 6 months) indicates the lifespan of the current refresh token. Each token exchange using a refresh token provides a new refresh token valid for another 6 months. Clients can continue this token exchange process for up to \~6-24 months.

## Token exchange flow

The token exchange flow in OAuth 2.0 allows clients to obtain new access tokens using refresh tokens, ensuring continuous access to resources without requiring users to re-authenticate. Here’s how the token exchange process works:

* Obtain Refresh Token: Ensure you have a valid refresh token, which was issued along with the initial access token.
* Send a request for the authorization server to exchange the refresh token for a new access token. This request should include:
  * **grant\_type**: Set to refresh\_token to indicate that you are using a refresh token.
  * **refresh\_token**: The refresh token obtained from the previous access token request.
  * **client\_id** & **client\_secret**: This combination is used as basic authentication (base64 encoded)

<br />

```shell
curl --location 'https://id.my.candis.io/auth/realms/candis/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization:Basic $(echo -n "<ClientId>:<ClientSecret>" | base64)' \
--data-urlencode 'refresh_token=<RefreshToken>' \
--data-urlencode 'grant_type=refresh_token'
```

<br />

The server responds with a new access token set, the duration until the token expires.