Skip to content
Trimble Identity

Refresh a token

Access Tokens are short-lived and must be refreshed after they expire to continue accessing resources. You can refresh the access_token by submitting another POST request to the /token endpoint, but this time providing the refresh_token as the grant type.

In Trimble Identity, an access_token is valid for 1 hour, and Refresh Tokens are valid for 9 days. However, errors can occur when tokens expire, are revoked, or lack sufficient privileges. Please ensure application can address errors returned by the token issuance endpoint.

Example request

Section titled “Example request”
POST /token HTTP/1.1
Host: stage.id.trimblecloud.com
Authorization: Basic OGgxY...
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache


grant_type=refresh_token&scope=<scope>&refresh_token=f77a8...

Example response

Section titled “Example response”
{
  "scope": "openid",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "861e9...",
  "id_token": "eyJhbG...",
  "access_token": "8aca1..."
}
  • To decode and verify the TID JWT Token, refer to Decode JWT

  • API CALL:

    • POST {baseURL}/oauth/token

  • HEADER:

    • Authorization: Basic <Base64 encoded “ClientID:ClientSecret”>
    • Accept: application/json

  • REQUEST BODY

    • grant_type = refresh_token
    • refresh_token = {the refresh token generated during the last access token request}

The value of id_token is only returned if id_token was included in the response_type of the original /authorize request.

Refresh token grace period

Section titled “Refresh token grace period”

The grace period feature replaces deletion of a refresh token after it is exchanged, allowing users to retry token refresh during temporary network interruptions. By default, the grace period is one hour.

The grace period is configurable at application level and requires an approval process from the product team. Kindly raise a ticket with our support team.

Format of refresh token configured with Grace period

Section titled “Format of refresh token configured with Grace period”
dataRegion_newToken_rootToken

where

  • dataRegion - the geo-location of the user (US, EU, EU-GB, AP-AU).

  • newToken - current node token generated in the hierarchy after exchanging the rootToken or the parent token in the chain.

  • rootToken - the first token in the chain of hierarchy generated from authorization code grant.

The root token would own the hierarchy and thus its format would be dataRegion_rootToken_rootToken

Refresh Token clean-up scope

Section titled “Refresh Token clean-up scope”

Trimble Identity removes refresh tokens (RTs) in the scenarios below. The cleanup scope depends on the trigger — from a single token to all RTs for a user or under a root RT chain.

# Trigger (user action) Cleanup scope Behavior
1 Password change / password recovery All RTs of the user Deletes all issued RTs, session cookies, and performs global sign-out.
2 User delete request All RTs of the user RTs and sessions cleared immediately when the delete request is registered.
3 Account purge (after delete request grace period, or admin delete request) All RTs + third-party integration RTs All issued RTs are batch-deleted as part of removing every user resource.
4 Refresh token usage (rotation) The used RT (and stale sibling RTs) Grace period disabled: used RT deleted immediately. Grace period enabled: all previously issued RTs under the same root RT (except received + new) are deleted; the used RT is retained only for the configured grace TTL.
5 Suspected leaked / replayed RT All RTs under the root RT If a presented RT is not registered and is in the new format, every RT issued under its root RT is deleted defensively.
6 Explicit revocation / sign-out The presented RT Token deleted; endpoint always returns 200 OK.
7 Admin sets temporary password for managed user All RTs of the user RTs cleared when a new temporary password is applied.
8 Region migration All RTs of the user (source region) RTs are wiped in the source region when user data moves to another region.
9 Token expiry (no user action) The expired RT RT records carry a time_to_live attribute; DB TTL-based cleanup.
Section titled “Related”