Authentication

Get the token

The API uses an access token obtained from POST /oauth/token. It is the only endpoint that does not require a token: it takes the platform username and password in an application/x-www-form-urlencoded body, with grant_type always set to password.

The scope field is optional. The collection states that, when omitted, the token is issued with read, write and trust, and that any of them authorizes every route of the API.

Lifetime

The access_token is valid for 12 hours. The response carries expires_in in seconds. When the token expires, authenticate again at the same URL and repeat the call.

Send the token

Every other call carries the token in the Authorization header, with the Bearer prefix. Without the prefix the request is rejected with 401.

Authorization: Bearer {{access_token}}

When the response is 401

On the token endpoint, 401 means invalid username or password, and the body carries error and error_description.

On every other route, 401 means a missing, malformed or expired token. The handling is the same in all three cases: authenticate again and repeat the call.

When the platform calls your system

For callbacks and webhooks the direction is reversed: CWS Platform authenticates against your system before calling your endpoint. The expected token format and the accepted models are on the webhook pages.