Authorization Code

In the Authorization Code flow, a code is returned to the client through a browser redirect after the user (resource owner) gives consent to Identity (authorization server). The client subsequently exchanges the authorization_code for an access_token. Users’ credentials are never exposed to the application (client).

The Authorization Code grant type is intended to be used by user-facing web applications with a server-side component. When the user grants authorization, the Identity authorization endpoint provides the client with a short-lived authorization code.

How It Works

The application opens a browser to send the user to the authorization server login page
The user performs a standard login with Trimble ID credentials
The user is redirected with the Authorization Code in the query string
Trimble ID returns an ID token to an application which validates the signature
The application exchanges the Authorization Code for an access_token and a refresh_token
The access_token is used to authorize the application.

What You Need

You will need the following information from Trimble:

Client ID
Client secret
Callback URL

Credentials

This documentation refers to credentials. Credentials are Base64 encoding your combined Client ID and Client secret separated by a colon, e.g.: Base64(id:secret).

Authorization

Request

The first request is a GET or redirect to the authorization endpoint (/authorize) performed in a web browser. The /authorize endpoint supports three response_types: code, id_token, token. If code is present in your parameters, JWTs are not needed for authorization.

If the request contains the OpenID scope, it is also considered an authentication (OpenID Connect) request, and an ID token is issued.

GET /oauth/authorize

Parameters

Parameter	Description
state	This field is used to return data (like a return URL) after sign-in with an access code.
client_id	Application ID registered for the application (UUID)
response_type	`code`
scope	`openid` and scope(s) needed to enable intended functionality as documented for each API product to which access is being granted.
redirect_uri	Redirect URL registered with Identity
ui_locales (optional)	Locale value. This specifies locale language Identity v4 UI will display. This value is optional.
prompt (optional)	How Trimble ID displays the login UI.
login_hint (optional)	Allows an application to specify the email address for use in the sign in or sign up page if you are using prompt=create
account_id (optional)	IAM account ID for this sign-in. Pass it to select that account for the tokens issued by `/token`. Omit it to use the user’s default account.

Prompt Options

Possible values for the optional prompt parameter

Prompt value	Description
none	Trimble ID will not display any UI, if there is no SSO session the /authorize call will redirect to the caller with a error
login	Trimble ID will always display the sign in UI, regardless of whether an SSO session exists
create	Trimble ID will display the sign up page rather than the sign in page

Account context

account_id is optional on GET /oauth/authorize. Pass it when the application must sign the user in under a specific IAM account. This is how an application switches account context programmatically. The access_token and id_token from the following /token call include that value as the account_id claim.

A valid account_id that is associated with the user is returned as the account_id claim in the access_token and id_token.
When account_id is omitted, Trimble ID uses the user’s default account when it mints those tokens.
An invalid account_id, or one that is not associated with the user, redirects to the callback URL with an error.

To switch to a different account, start a new /authorize request with the new account_id, then exchange the new authorization code at /token.

Response

The following is an example of the callback made to your callback endpoint. You will need to parse the code parameter from the callback to use in your token call.

http://localhost:5173/auth/callback?
code=us_9fd5fee3f3c74267910f8ed7c71c85a8&
state=Hn4K-n1m00000CiUUV-vOUNcOJZ8Jh_4shoo

Token

Request

After acquiring the authorization code, you exchange an authorization code for an access token through the resource server.

POST /oauth/token

Headers

Header	Description
Authorization	Basic `credentials`
Accept	application/json
Content-Type	application/x-www-form-urlencoded

Body

Body	Description
grant_type	authorization_code
code	The authorization code returned from the above call
client_id	Application ID registered for the application
redirect_uri	Callback URL registered with Identity

Response

If the token request succeeds, the server responds with a 200 response code.

Fields

Field	Description
access_token	The access token’s primary function is to authorize a user.
refresh_token	A refresh token is used to obtain access tokens after an initial authorization grant without interaction with the end-user.
expires_in	The duration of time the access token is granted for in seconds
id_token	An ID token is an artifact that proves the user has been authenticated. The ID token contains information about the user, such as user name and email, and is used to authenticate a user.

The access_token and id_token are JWTs. Each includes an account_id claim for the account selected on /authorize. When that request included account_id, the claim is that account. When it did not, the claim is the user’s default account.

Example

{
  "access_token": "8aca1...",
  "refresh_token": "861e9...",
  "expires_in": 3600,
  "id_token": "eyJhbG..."
}

Refresh

If the access token expires, it can be refreshed using the one-time refresh token.

The server will respond with a Token Response.

POST /oauth/token

Headers

Header	Description
Authorization	Basic `credentials`
Accept	application/json
Content-Type	application/x-www-form-urlencoded

Body

Body	Description
grant_type	refresh_token
refresh_token	The refresh token from the previous token response