Skip to content
Trimble Identity

Use token exchange (on-behalf) grant (Class #1)

The token exchange grant allows an application to act on behalf of a user. The token exchange grant is only supported for access tokens. It does not work with any other type of token, including refresh tokens.

When to use this

Use token exchange (on-behalf-of) when:

  • The workflow completes in under one hour and is not repetitive (Class #1 in Asynchronous workflows with Trimble ID).
  • The subject is present when the workflow starts, and the initial access token remains valid for the entire chain.
  • Each application in the chain only needs to call the next service before that token expires — no token store or refresh tokens are required.

For longer or repetitive workflows, see Use refresh tokens for on-behalf-of (Class #2) or Use subject delegation for long-running repetitive workflows (Class #3).

On behalf grant is based on RFC 8693 Spec. Only a subset of the RFC has been implemented. Currently supported parameters:

  • grant_type
  • scope
  • subject_token_type
  • subject_token

These tokens are not revocable. Hence, use it with caution and take precautions to avoid token leakage

How it works

Below are two cases for the on behalf grant that can help clarify any issues you may be running into.

Case 1: using authorization code grant with on behalf

  1. An authorization code request is submitted for the application.
  2. The request is authorized by the user.
  3. The user is then redirected with the authorization code in the query string.
  4. Using /token request, the obtained authorization code is exchanged for an access token and ID token.
  5. These tokens are the subject token in the request body that has to be used in the on behalf exchange token call.

Case 2: using authorization code with PKCE

  1. Create the code_verifier and code_challenge, see Authorization Code with PKCE instructions.
  2. Submit the generated code_challenge with your /authorize request.
  3. The authorization server returns an authorization_code once the user authorizes the request.
  4. Then the code_verifier and authorization_code values are submitted to /token endpoint.
  5. The server responds with the id_token, and the access_token.
  6. These tokens are submitted as the subject_token for the on behalf exchange token.

While submitting the /authorize request (Step 1), ensure that all applications/audiences to whom the access is delegated for is passed in the ‘scope’ parameter. The applications listed in the scope can only use the exchanged token.

Creating an on behalf call

  • API CALL:

    • POST {baseurl}/oauth/token

  • HEADER:

    • Authorization: Basic {Base64 encoded ClientID:ClientSecret}
    • Accept: application/jsonClientID and ClientSecret should come from the originating application

  • REQUEST BODY:

    • grant_type = urn:ietf:params:oauth:grant-type:token-exchange
    • subject_token = {the access token to exchange}
    • subject_token_type = urn:ietf:params:oauth:token-type:jwt
    • scope = {target_application or api_name} (Multiple scopes may be space delimited)

Use the scope parameter to authorize your internal APIs

Example request

Host: stage.id.trimblecloud.com
Accept: application/json
Authorization: Basic VmNqW...
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache




subject_token=eyJhbGciO...&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt&scope=processing

Example response

{
      "access_token": "eyJ4NXQiO...",
      "issued_token_type": "urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt",
      "token_type": "Bearer",
      "expires_in": 3600
  }
  • To decode and verify the TID JWT Token, refer to Decode JWT