Tokens & Refresh
This page explains the tokens the platform issues, how long they live, and how to refresh them.
Tokens carry no developer-requested scopes. Access is fixed by the attributes set on your client when its credentials were created (the vehicles and data categories). To change what a token can reach, change the client's configuration in the portal.
Token types
| Token | Purpose | Used by |
|---|---|---|
| Access token | Short-lived credential presented to the REST API (with DPoP) or used as the MQTT connection password. | All personas. |
| Refresh token | Longer-lived credential used to obtain a new access token without re-running the full flow. | Authorization Code and Device Code flows. |
The client credentials grant typically returns no refresh token. When a client-credentials access token expires, simply request a new one with the same client-credentials call.
Lifetimes
| Token | Lifetime | Notes |
|---|---|---|
| Access token | 3600 seconds (1 hour) | Refresh or re-request before it expires. |
| Refresh token | 1 209 600 seconds (14 days) | When it expires, re-run the originating flow. |
Each response reports its own lifetime in expires_in (and refresh_expires_in
where applicable). Always rely on those values rather than hard-coding durations.
Refreshing an access token
For the Authorization Code and Device Code flows, exchange the refresh token for a fresh set of tokens. Authenticate the client with a client assertion, and because the new access token is DPoP-bound, include a DPoP proof:
curl -X POST https://auth.jlr-vcdp.com/realms/public/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "DPoP: YOUR_DPOP_PROOF_JWT" \
-d "grant_type=refresh_token" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-d "client_assertion=YOUR_SIGNED_ASSERTION_JWT" \
-d "refresh_token=YOUR_REFRESH_TOKEN"
A successful refresh returns a new access token (and usually a new refresh token), resetting the expiry timers. Refresh before the access token expires to keep a continuous session.
When to re-run the full flow
Re-run the originating flow (not a refresh) when:
- The refresh token has expired.
- The customer's consent was withdrawn and later re-granted.
- The client's configuration changed (different vehicles or data categories) and you need a token reflecting the new configuration.
What a token can access
The platform does not use developer-requested scopes. A token can only reach what its client was configured for when the credentials were created:
- Vehicle owners - the specific vehicles (VINs) and data categories selected.
- Third-party developers - the data categories (required and optional) the customer consented to.
- Fleet operators - the vehicles registered to the fleet.
To widen or narrow access, update the client's configuration in the portal and, if necessary, re-run the flow. There is nothing to request at authentication time.
Next steps
- Client Assertion - Sign the JWT every token request needs.
- DPoP - Required for every REST request.
- REST API - Use your access token.
- Streaming - Use your token as the MQTT password.