Authentication and Authorization

All our REST based APIs are secured by the OAuth 2.0 protocol using our Authorization Server. The Authorization Server supports several flows for single page application, native device apps and server based applications. OAuth 2.0 is a fairly simple protocol, and a developer can integrate OAuth 2.0 without too much effort. On this site you will find documentation on how to use the OAuth 2.0 endpoints provided by the Authorization Server, to obtain access tokens to call a secured API.

To be able to obtain an access token for your app or service. You should first register your organisation and request an integrator account. After registration you will receive a OAuth ClientId and Client Secret.

Quickstart

1. Create an account and register your organisation

Visit Xynaps and sign in or follow the register link to create a new account.

Note

Make sure that you provide us with all the necessary information to validate, your application for an account and to validate the organisation you work for. Please use a correct e-mail address, phone number and VAT Identification number for your organisation.

2. Request an access token from the Xynaps Authorization Server.

Before your application can access a Xynaps API, it must obtain an access token that grants access to that API.

The Xynaps Authorization Server support a number of ways to request an access token. Depending on your scenario, you can use the following OAuth 2.0 grants:

  • Implicit Grant
  • Authorization Code Grant
  • Client Credentials Grant
  • Resource Owner Credentials Grant

3. Use the access token to access the Xynaps API.

After you have obtained an access token, you can use it an HTTP authorization header. We do not support sending access tokens in the query string, as these query string parameters can be logged in log files that are not completely secure. The validity of an access token is determined by its lifetime and the scope requested during the token request.

For example:

GET /api/v2/transportdocuments/12 HTTP/1.1
Host: apps.xynaps.net
Authorization: Bearer 164ajioAEJ6868yUpkk831385

4. Refresh the access token, if necessary.

As mentioned in the above steps, access tokens have limited lifetimes. If your application needs access to a Xynaps API beyond the lifetime of an access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

Note

Save access and refresh tokens in secure storage and continue to use them as long as they remain valid. Limits apply to the number of refresh tokens that are issued per client-user combination, and per user across all clients, and these limits are different. If your application requests enough refresh tokens to go over one of the limits, older refresh tokens stop working.