Authentication and Token Generation for API usage

Copyright IBM Corporation and Maersk GTD 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 user then supplies this bearer token to the platform to authenticate themselves 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.

Token Generationa1b

(Figure 1: general login flow)

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 had 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 was associated with a Service ID, and this Service ID was 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 steps for login follow the general login flow in figure 1. The user code calls the Cloud IAM login endpoint "/oidc/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:

Detailed steps:

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

    Notes: 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.

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

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

    • Important: Copy and Save the "ServiceId" value at the top of the screen, for example: "ServiceId-4807b3fb-11d9-4304-b3da-8205a77d6f8a"

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

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

    • Important: Click the Download button and save the value of the API key. Token Generation11b

    • After you have downloaded and saved the API key, click the Close button.

  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.

    • Register or Create a system user in User Management

    • 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 Bluemix 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. Submit the request by clicking Add New User. Token Generation6b

  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:
      POST HTTP/1.1
      Header: Content-Type: application/x-www-form-urlencoded
      Body: grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=your_api_key

      For example: Token Generation12b

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

      For example: Token Generation13b

  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 (you can also find your organizationId from the Solution 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/solution_id_for_zone/organization/organization_id
      Header: Content-Type: application/json
      Body: contents_from_response_cloud_iam_in_previous_step in raw format

      For example: Token Generation14c

    • Expect a response which includes the Solution Manager exchange token

      For example: Token Generation15b

  5. To call the 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 /api/v2/consignments - start consignment tracking. Note: The Carrier will normally be the organization that issues the start for the consignment, but we will be submitting this event for illustration purposes.
    Token Generation16d Token Generation17d

    Example response: Token Generation18d

  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 403 will be the response. The calling code should check for a 403 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.