Authentication

Organizations may use the Livvi API with OAuth2 Client Credentials authentication.

In the client credentials authentication scheme, you may generate an authentication token by providing a clientSecret and a clientId.

The resulting access token will have a validity of 12 hours and should be sent as a Bearer token on other requests.

Getting your token

Make sure you have the clientId and clientSecret for your corporation. If not, please contact Livvi support.

On the Authorization header, you should send "Basic <credentials>", where <credentials> should be "<clientId>:<clientSecret>" in Base64 encoding.

For example, if your clientId is client and your clientSecret is secret, the base64-encoding of the string "client:secret" is "Y2xpZW50OnNlY3JldA==".

Therefore, in this example, you should authenticate all requests with the header "Authorization: Basic Y2xpZW50OnNlY3JldA==".

API address: https://api.athos.vingcard.com

Endpoint: /corp/auth/m2m

HTTP method: POST

HTTP Request (example with cliendId = client and clientSecret = secret):

POST https://api.athos.vingcard.com/corp/auth/m2m
Authorization: Basic Y2xpZW50OnNlY3JldA==

{
  "accessToken": "ey...",
  "expiresIn": 43200,
  "expiresAt": "2024-10-26T06:52:09.443Z",
  "scope": "read:corp write:corp"
}

For example, the following requests should have the header "Authorization: Bearer ey...", where ... represents the rest of the access token.

Token caching

The /corp/auth/m2m endpoint caches the token for you. Therefore, the endpoint will return the same token until it has less than 30 minutes to expiration.

The expiresIn property will reflect the actual time remaining until the token expires.

We recommend you schedule a call that refreshes the token to 5 minutes before token expiration.

If any API call using the token returns a 401 HTTP status, you should retrieve a new token.

Get your client ID and secret