Auth

Authentication

Requests sent to version 3 of our web services are secured using a Json Web Tokens (JWT). Please contact your Account Manager to obtain your client credentials.

How to obtain a JWT Token

JWT tokens are obtained by sending a request to the /auth/connect/token endpoint passing it the client id and client secret in the request body. For example:

POST /auth/connect/token HTTP/1.1
Host: ws.integration.banyantechnology.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 113

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}

Your client id and secret should be URL Encoded

If authenticated successfully, an object is returned in the response with the property access_token being the JWT token.

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "shipments.view"
}

How to use the JWT Token

The JWT token can be used for Bearer Authentication. It's passed in the
Authorization header as the following:

Authorization: Bearer {jwt_token}

Client Ref Number

In version 2 of our web services, a ClientRefNum value was passed in the AuthenticationData object in the request body.

To use this same functionality in version 3, you can simply pass the same value in your token request. For example:

POST /auth/connect/token HTTP/1.1
Host: ws.integration.banyantechnology.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 113

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&clientrefnum={{client_ref}}

This will associate the returned access_token to the specified client and any actions in the system will be associated to that client.

OAuth 2.0

You can learn more about the OAuth 2.0 Client Credentials Grant by going to tools.ietf.org/html/rfc6749#section-4.4