Skip to content

Authentication and Token Generation for API usage

Copyright IBM Corporation and GTD Solution Inc. 2018, 2019

This procedure is needed for systems integrating with the TradeLens platform, for example, a system user (program code) that calls the APIs.


  • Important: If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in any of the URLs below that have "platform" in the domain.
  • Due to continuous enhancements, some of the functions and screen images might be different than what you see on the current level of TradeLens.
  • The URLs could change in the future; it is recommended that you use environment variables.


Cloud IAM: The IBM Cloud Identity and Access Management service used to manage user logins, see A user logs into cloud IAM and receives a token they can use to prove their identity.

Solution Manager: This is the service that TradeLens uses to track provisioned (onboarded) organizations in the TradeLens platform. Each organization has a set of permissions allowing it to take certain actions within TradeLens applications. Users are associated with any number of orgs and when they log into Solution Manager they are granted a bearer token identifying them as a member of one organization (that the user chooses at login time from the list of orgs with which they are associated). The bearer token is supplied to the platform to authenticate the user as a member of that organization.

Organization: A entry in the Solution Manager representing a company, port authority, national customs authority, and more, that tracks what operations the organization is allowed to perform in TradeLens applications. When a user is onboarded into TradeLens, TradeLens will create an Organization for them and store the organizationId in the Solution Manager. Members of the company that organization represents will be able to log in and obtain a bearer token indicating that they are a member of that organization.

Solution: A grouping of organizations within the Solution Manager. Every organization is part of exactly one solution. To log in and obtain a bearer token for an organization, you will need to know the solution ID of the solution that organization is a part of: for the sandbox zone, this is "gtd-sandbox"; for the production zone, this is "gtd-prod".

Access token: The name of the token returned when logging into Cloud IAM. This is an intermediary token that is passed to Solution Manager in order to retrieve the final bearer token.

Bearer token: A token placed in the header of an HTTP request to authenticate and identify the user making the request. A user of the TradeLens platform obtains a bearer token from Solution Manager that identifies them as belonging to a particular organization (Solution Manager calls this the "onboarding token" when they pass it to the user).


In order to use the TradeLens platform application to call any of the API endpoints as a system user with program code, the platform requires you to first log into an identity service called Solution Manager. Solution Manager keeps track of organizations that have been provisioned for TradeLens, meaning that members of the organization are allowed to use the platform APIs. Once you have logged in, Solution Manager grants you a "bearer token", a string that identifies who the user is. You then pass this bearer token in a header for all your API calls to the platform.

Logging into Solution Manager is a two-step process. You must first obtain an "access token" from another identity service known as "Cloud IAM". Then you call an endpoint in the Solution Manager API where you pass the access token as a parameter and receive a bearer token. This separation of the login process is done to keep the list of users (managed by Cloud IAM) separate from the list of organizations (managed by Solution Manager).

If you are using the APIs through Swagger for testing, the authentication process is handled for you through your login. See the API Documentation section for more details.

System user details

The case for a system user or application (block of code) to log in has two major differences from a human user logging in. First, whereas the human user has redirects to hide the two-step process of Cloud IAM → Solution Manager, a piece of code logging in has to manage the Cloud IAM step itself. Second, rather than a username and password, the application will only have a single key known as the API key that it will provide to Cloud IAM. This API key is associated with a Service ID, and this Service ID is associated with an organization in TradeLens. Having the API key is sufficient credentials to log in as a system user that is a member of the given organization. The user code calls the Cloud IAM login endpoint "/identity/token", supplying the API key as a parameter. This returns an access token. The user code then calls the "/v1/iam/exchange_token/solution/{solutionId}/organization/{organizationId}" endpoint in Solution Manager, providing the organizationId to which the user code intends to log in, the solutionId in which that org lives, and the access token received from Cloud IAM (the solutionId is "gtd-sandbox" for the sandbox zone and "gtd-prod" for the production zone). Solution Manager will return a bearer token that identifies the system user as a member of the chosen organization. The user code is responsible for storing this token and putting it into the authorization header of all HTTPS calls made to the APIs.


High level summary of steps:

  1. Create a service ID and create an API key
  2. Create a system user - this connects the API key with system user
  3. Use the API key to generate the IAM access token and refresh token
  4. Use the IAM access token and refresh token as a body to generate the Solution Manager exchange token
  5. Use the Solution Manager exchange (bearer) token to publish or subscribe
  6. Handle Solution Manager exchange token expiration: before calling TradeLens APIs, check for expiration of the Solution Manager token, and if expired, go back to step 3

Note: The steps for getting the bearer token are detailed below. Steps 3-5 are for illustration purposes and use a posting mechanism to show the flow. However, you will most likely use code to perform steps 3-5 in your application and automate the process of getting an initial token, getting a new token if it has expired, and calling the APIs with the token. Here is some sample code (provided "AS IS" without warranty) that models this behavior:

The sample code above ( mentions SOLUTION_MANAGER_PUBLIC_KEY. To obtain a public key, use the following Blockchain Solution Manager endpoints, depending on the zone.

  • Sandbox: GET
  • Production: GET

The response is an array of public keys. You can use any one of the keys for SOLUTION_MANAGER_PUBLIC_KEY. For more details on the Blockchain Solution Manager .../onboarding_pem API, see the Swagger for Sandbox at and Production at

Detailed steps:

  1. Create a Service ID. If you already have a Service ID, skip to step 2.

    Note: The user that is creating the Service ID must be registered with IBM Cloud at in order to use the IAM service. An organization can have multiple Service IDs, but it is a best practice to not use the same Service ID for more than one organization.

    • Navigate to and sign in with your IBMid. If you do not have an IBMid, you can sign up here.

    • Click Manage in the top menu, then select Access (IAM). Token Generation2a

    • Select Service IDs on the left and click the Create button. Token Generation7c

    • Enter a name and description. Click the Create button. Token Generationa7c

    • Important: Copy and Save the "ServiceId" value displayed by clicking Details near the top right of the screen, for example: "ServiceId-b93c3524-3846-497f-a568-087a3b6e5ad6". The Service ID is used as a System User in the User Management section for TradeLens. We will show this in step 2. Token Generationb7c Token Generationc7c

    • Click the API keys tab and then click the Create button. Token Generation8c

    • Enter a name and description. Click the Create button. Token Generation10c

    • Important: Copy or Download the API key and save it. The API key is used to get an access token from Cloud IAM. We will show this in step 3. Token Generation11c

    • After you have saved the API key, close the dialog box.

  2. Create a system user using the Service ID from step 1. If you have previously created the system user in TradeLens and associated it with your Service ID, you can skip this step. The system user can be created by an admin for your organization from the User Management UI, or through the APIs. This step connects the Service ID and API key to Solution Manager for your organization. Note: At least one Admin ID will be created during the provisioning (onboarding) process for your organization. Additional Admin IDs can be created from an existing Admin ID.

    • Log into TradeLens with your Administrator ID on Sandbox ( ) or Production ( ) to access the Shipment Manager (SM) UI. Click on Account, then click on User Management, then click on Add New User. Token Generation4i Token Generation5g

    • In the "Add A New User To Your Organization" popup window:

      1. Select the System User checkbox.

      2. Enter the Service ID that was created from the Cloud IAM Service ID process (enter the entire Service ID, including the "ServiceId-" portion).

        Note: An organization can have multiple Service IDs, but it is a best practice to not use the same Service ID for more than one organization.

      3. Enter a brief description.

      4. You can also select the Administrator checkbox if this Service ID will be used as an administrator.

      5. Submit the request by clicking Add New User. Token Generation6c

  3. Get an access token from Cloud IAM. Use the API key that was created as part of the Service ID process in step 1, or one that you had created before.

    • Send this request:
      Header: Content-Type: application/x-www-form-urlencoded
      Body: grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=your_api_key

      For example (Note: raw was selected in the image below to show the body, but x-www-form-urlencoded should be selected when sending the request): Token Generation12c

    • Expect a response like:
      "access_token": "ABC....",
      "refresh_token": "XYZ...",
      "token_type": "Bearer",
      "expires_in": 3600,
      "expiration": 1520976069,
      "scope": "ibm openid"

      For example: Token Generation13c

  4. Get an exchange token from Solution Manager ( Sandbox: and Production: ).

    You will need to know:

    1. Your organization ID. The organizationId was provided to you as part of the TradeLens provisioning process (if you are an organization admin, you can also find your organizationId from the Shipment Manager UI User Management section), for example: 98e2f3cc-e801-4a34-9eef-e4b2e3a65ff1.

    2. Your solution ID. This is the ID of the solution into which your organization was provisioned. This will be "gtd-sandbox" for the sandbox zone, and "gtd-prod" for the production zone.

    Using your organization ID and your solution ID:

    • Send this request, where Solution_Manager_domain is: for Sandbox, and for Production:
      POST https://Solution_Manager_domain/onboarding/v1/iam/exchange_token/solution/
      Header: Content-Type: application/json
      Body: contents_from_response_cloud_iam_in_previous_step in raw format

      For example: Token Generation14d

    • Expect a response that includes the Solution Manager exchange token

      For example: Token Generation15c

  5. To call the TradeLens APIs, use the Solution Manager exchange token from step 4 by setting it in the Authorization header as ”Bearer Solution_Manager_token".

    Three headers are required on the HTTPS request: Accept, Content-Type, and Authorization.

    For example, here is an API call for POST .../consignments - start consignment tracking. Note: The Transport Service Provider, for example a Carrier, will be the organization that issues the start for the consignment, but the process is the same for any of the APIs.
    Token Generation16e Token Generation17e

    Example response: Token Generation18e

  6. Handle Solution Manager exchange token expiration.

    The Solution Manager exchange token is valid for 3 hours. When the Solution Manager token expires, only then is a new token required from Cloud IAM. Client code should not cache the IAM access_token, but instead get a new one when the Solution Manager token expires. So, the process should be: obtain Cloud IAM token => get exchange (bearer) token from Solution Manager => cache and check for expiration of only the Solution Manager token and if it's expired, get a new Cloud IAM token and Solution Manager token. Note that the token could expire right as it is being used. If this happens, a 401 will be the response. The calling code should check for a 401 and handle it by getting a new Cloud IAM token and Solution Manager token.

    This is what the sample Java code (discussed at the top of this procedure section - is doing:

    • getBearerToken() is called before sending any request. It checks if the token is still valid, checks expiration on checkSMToken(). If it has expired, then it calls loginToSM();, which "re-starts" the loop by calling IAM to get new token and exchanges it with Solution Manager token.