Authentication ‐ Auth

HTTP request with user & password in the header

Endpoint

POST /api/auth

Headers

• Authorization: Basic AUTHORIZATION_DATA
  AUTHORIZATION_DATA must be base64 encoded string that concatenates username, :, password, e.g. in PHP it would be something like this: $authorization_data = base64_encode('username' . ':' . 'password');
• Content-type must be one of following:
  • Content-Type: application/json
  • Content-Type: application/x-www-form-urlencoded

Payload

Payload must contain info about id of the workspace that we want to get access to.

• If Content-Type is application/json then body of the request should be like this:{"workspaceId": 1}
• If Content-Type is application/x-www-form-urlencoded then payload should look like this:workspaceId=1

Response

Response is always in JSON format, no matter of Content-Type header set in the request (this is the same for other calls as well).

• See Invalid response in Standard response rules
• Valid response returns token to use in subsequent requests for authentication and authorization reasons along with ttl saying for how long token will be valid.

        {
            "valid": true,
            "data": {
                "token":"AUTH_TOKEN",
                "ttl": 3600
            } 
        }

Using authentication token

Once we have token we can access other endpoints that require it (basically all API calls apart from the api/auth endpoint). Token can be inserted in a couple different ways:

• as a parameter in the query part of the url endpoint, e.g. /some/endpoint?token=AUTH_TOKEN
• as a special header X-Auth-Token, e.g. X-Auth-Token: AUTH_TOKEN
• as a part of the POST payload, only if request is of the POST type. In such case:
  • if Content-Type is application/json then body of the request should be of JSON type and transmitted JSON object should contain token property containing value of the AUTH_TOKEN, e.g. something like this: {"token":"AUTH_TOKEN","other":"property"}
  • if Content-Type is application/x-www-form-urlencoded then token should be one of the parameters, something like this: token=AUTH_TOKEN&other=property