All RightShip APIs requires authentication, which we delegate to Auth0. Auth0 enables secure access to our APIs from third-party apps.
The authentication process uses the open standard OAuth2 Client Credentials Grant to ensure secure communications. For further information on the flow, you can refer to the Auth0 docs.
Authenticating
Authentication is achieved via three steps:
Your application authenticates itself with Auth0 using a
client_idandclient_secretthat RightShip will supply to you once your account is provisioned.Auth0 validates this information and returns an Access Token.
Your application can then use the Access Token to call RightShip APIs.
For reference, an Access Token will be returned in the form of a JSON Web Token (JWT).
Note: you will initially be provided credentials for RightShip's Staging (or Test) environment only. Production credentials will then be supplied only after testing is complete and a commercial agreement is in place. When authenticating in Production, use an audience value of rs:rightship-platform instead.
Example
Response sample:
For a more detailed example, please see Authorization Code Flow in the Auth0 Authentication API docs.
Calling a RightShip API
When calling a RightShip API you must supply the Access Token as a Bearer credential in an HTTP Authorization header. For an example, see the Vessels API.
When you make a call to any of the RightShip APIs, the API will validate the Access Token and that your account has permission to access the endpoint you are calling. If either check fails, you will receive a 401 Unauthorized result.
If validation is successful, the API will return an appropriate response, usually with a 200 OK result. At this point, you can start exploring the RightShip APIs.