Sign in



DeliveryHub Help

Search DeliveryHub Help

API configuration setup

Avatar
Malene Tidemann
Updated

 

If you are using an API in Portal that requires the use of tokens (Client IDs and Client Secrets), this article will explain how to generate it. 

Please note that only "owner" and "admin" users have access to the API Configuration page. It is recommended to create a specific admin user for API interaction. For example, on the Shipment Data API, it would allow you to customize the shipment viewer profile to match the exact data you want to return, without affecting other users' configuration for UI.


If you are unfamiliar with the user types and roles used in DeliveryHub, we recommend reading this article: Understanding user types and roles.

Our recommendation for all Portal Apis is to use the HTTPS (version TLS 1.2 minimum) in order to function properly and have enhanced security with these products. Support for TLS 1.0 and 1.1 will be deprecated in the future. TLS 1.0 and 1.1 are out-of-date protocols that do not support modern cryptographic algorithms, and they contain security vulnerabilities that may be exploited by attackers.

 

Creating a Client ID and Client Secret

  1. Log into Portal with your owner user.

  2. Click on your name in the top right corner and choose Settings.

    settings.png

  3. Choose API Configuration > Clients in the left side menu.

  4. On the Clients page, click the Add button.

    add-clients-api.png

  5. In the dialog box that opens up, fill in Display name and Description. Choose a name and a description that will make it easier to identify the token later on. Check the Enable box to enable the token right away. (You may enable or disable the token at any time after it has been created).

    client-api.png

  6. Choose the Allowed Scopes. We recommend always including OpenId and choosing your needed API options. 

    allowed-scopes.png

  7. Click Save. Your Client Id and Client Secret will now be generated and displayed on the screen. Important: Note the tokens as Client Secret will not be available after you close the popup.

    client-secret.png
  8. Click Save to finish creating the token.

  9. The token will now be listed on the Clients page. You can click on a token at any time to edit or delete it or to enable/disable it.  If you have a long list of tokens, you can use the filter option at the top to show only enabled or disabled tokens.


Overview of scopes

This list explains the usage of the different scopes. For security reasons, we recommend only choosing the scopes you need. It is better to create multiple Client IDs with narrow scopes than one ID covering multiple scopes. 

  • Your user identifier (openid) - Mandatory scope. Used during authentication to authorize access to a user's attributes and settings.

  • User profile (profile) - Provides access to profile information.

  • Public Containers API (public_containers_api) - Needed to use the container API to manage containers. Read more about the container API here. You also need this scope if you want to use containers in nShift On-premises, read more here.

  • Public COP Cloud Access (public_cop_cloud_access) - Used for secure communication between On-premises and Portal in order for subscriptions to run.
  • ScanApp public Api (public_api_scanapp_consignor) - Needed to use containers in nShift On-premises. This scope gives On-premises access to retrieve a list of available Action Centers based on the owner associated with the installation. Read more about containers in On-premises here.

  • Portal Shipment Data API (public_api_portal_shipment_data) - Needed when you want to use the Shipment Data API to retrieve shipment information from Portal. Read more about the Shipment Data API here.

  • Shipment Server (public_api_shipmentserver) - This scope is needed to use the Shipment Server API version 2. Read more here.

 

Getting an access token

Use your Client ID and Client Secret to generate an access token needed for other requests to our API. This is done by making a POST request to the following token endpoint:

https://www.consignorportal.com/idsrv/connect/token

Specify the Client ID, Client Secret and grant type in the language and framework used by your company.


Sample:
POST https://www.consignorportal.com/idsrv/connect/token 
Cache-Control: no-cache
Host: www.consignorportal.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

 

If the request is valid and the client is configured correctly, you will get back a JSON response:

{
    "access_token": "some-real-token-data-dskjfhsuijkdhfgjkasjdgfhqoeiefoiknsoidfgvoiltgjvpdrofjmwpkldujrftvoifgkhbnilsakjprotglijkqp2owrlfjkvmowrifgho2qw9ouejifpe9rodtuj3-0porfij9odtujgw0etioyh",
    "expires_in": 3600,
    "token_type": "Bearer"
}

 

Further reading

All our new APIs will support an OpenID solution for enhanced security. For more information, please see the OpenId and IdentityServer standard documentation:

Related articles