V1 and V2 authentication

The V1 and V2 APIs use bearer token authentication. Rather than sending your API key and password with every call, you exchange them once for a short-lived access token, then send that token in the Authorization header of every request. Any administrator on your Plytix account can issue the API key and password from the API tab in the account's Admin section.

This page documents the token exchange and how to use the token you get back. Use the access token returned by this exchange to authenticate API v1 and v2 requests.

Get a bearer token

To get a token, send your API key and password as the request body. Both fields are required:

Here's the full request and the response you get back:

curl --request POST \
  --url https://auth.plytix.com/auth/api/get-token \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "your.api.key",
    "api_password": "your.secret.api.password"
  }'

The token request goes to the authentication service at https://auth.plytix.com. Every other request goes to https://pim.plytix.com, under /api/v1 or /api/v2.

Send the token

Send the returned token in the Authorization header of every request, with a space after Bearer. Requests and responses on V1 and V2 use JSON, so set the content headers as well:

Content-Type: application/json
Accept: application/json
Authorization: Bearer your_access_token

Tokens expire after 15 minutes. When a token expires, or the API can't verify it, requests using it return 401 and you need to request a new token with the same exchange.

Error responses

If the token request fails, you get one of the following:

A 401 from the token request looks like this:

{
  "error": {
    "msg": "Bad api_key or api_password: Credentials not valid",
    "errors": [
      {
        "field": "http_status_code",
        "msg": 401
      }
    ]
  }
}

See Errors and status codes for the error format used across V1 and V2.