Connection Setup

All Client requests to retrieve or post data from/to remote Server systems using the Embedded Chain Gateway require a connection token. A connection token allows your application to make requests through the Gateway to a backend Server.

📘

Connection Tokens

A connection token is a signed JWT token that encodes the following information, used by the Gateway to service requests made by a Client Application on behalf of a user of that application

• environment - the environment in which the connection was created. Expected values are currently either "sandbox" or "production"
• client_id - the ID of the Client Application
• connection_id - unique identifier used to look up the remote server configuration setup by the user
• server_type - the type of Server that this connection is configured to connect to. Expected value currently is "cargowise", there is also a "sandbox" server type, this sandbox just returns dummy data and has no write capabilities.
• client_owner_id (optional) - identifier that may be set by the Client Application to associate a connection with a specific owner of the Client Application. Send your customer's name or customer number here for logging and tracing purposes
• scopes - a list of scopes representing the data and operations that (i) the Client Application has requested, and that (ii) the Owner Admin has explicitly approved during the configuration process

The contents of a connection token can be decoded using a JWT library for the programming language used by the Client Application. The contents can also validated by using this tool.

The process of setting up a connection is as follows:

1. In the Client Application the user will click a button or take a similar action to initiate the connection process with a Server
2. The Client Application will redirect the user to the Gateway setup landing page, using a query string containing the client_id, a list of required scopes, an optional client_owner_id, and a redirect_url to send the user to at the completion of the setup process
3. The Owner Admin will go through the process of selecting and configuring a connection to a backend Server
4. When the connection configuration is complete, the user will be returned to the Client Application via the redirect_url provided in step 2, along with an exchange token
5. The Client Application then makes a request to the (production or sandbox).embedded.chain.io/connection/token/exchange endpoint to receive a permanent connection token
6. The Client Application can use the permanent connection token from that point forward to make requests from the Gateway on the user's behalf

Sending the user to the setup page

The user should be redirected to production.embedded.chain.io/setup with the following items in a query string:

• client_id - provided to the Client developer when they registered with Embedded Chain.io
• scopes - a comma separated list of operations that the Client Application requires access to. See Scopes for more information
• client_owner_id - (optional) may be used by the Client Application to identify the specific Owner setting up the connection
• redirect_url - URL on the client application application that the user will be redirected upon completion of the connection setup. This URL can contain query string parameters if desired, e.g: http://clent-app.com/tms-setup-complete?customer_id=3933

Example Setup URL:
To begin the setup process the user would be sent to a URL similar to this:
https://production.embedded.chain.io/setup?client_id=a515d956-b418-4739-babd-9670d4a34025&scopes=SHIPMENT_READ&client_owner_id=user123&redirect_url=http://clent-app.com/tms-setup-complete?customer_id=3933

Upon completion of the connection setup, the user will be redirected back to the Client Application via the redirect_url, along with a status with one of the following values:

• "success" - an exchange token parameter will be returned as well
• "cancelled" - the user clicked a Cancel button during the connection setup process
• "error" - an error occurred during the setup process. The query string will contain an error_type as well as a possible error_sub_type and message. See Error Handling for more information about errors.

🚧

Parameter Validation

The /setup endpoint will first validate the parameter. If any of the following requirements are not met, the user will be immediately redirected to the redirect_url with a query string parameter of "status=error"

• Must have a valid client_id for a client in that environment. Identifiers from "sandbox" are not valid in "production", and vice-versa
• Must have at least one requested scope
• All scope values must be valid scopes as listed on the Scopes page
• Must have a valid redirect_url - if missing, an error will be reported to the user because the Client Application will not be able to automatically redirect the user

Token Exchange

Upon successful configuration of a connection, the user will be redirected to the client redirect_url with a status of "success", along with an exchange token.

The Client Application should post that exchange token along with the client_id and client_secret to the /connection/token/exchange endpoint.

The endpoint will return a connection token. This should be stored by the Client Application. To make a request to the Gateway on behalf of the user, e.g. Get Shipment, the Client Application must provide that connection token in the authorization header.