In this guide you will learn how to authenticate your API requests with long-lived tokens obtained by creating or retrieving an API key. This is a prerequisite for the other guides.

If you are unfamiliar with these concepts, follow their links or read the API reference introduction.

✦ Goal: obtain a long-lived token using your API keys and use it for authentication.

Prerequisites

1

Set up your HTTP client

Use the playground or automatically generate requests from the OpenAPI definition.

2

Authenticate using your credentials

Your API requests must be authenticated using your credentials.

Since only an authenticated user can create a new API key or view the existing ones, it is required that your first authenticate using your credentials.

Procedure

1

Create the API key

Create the API key to obtain the long-lived token associated with it. Skip this step if you already have an API key. See the API reference.

You must choose the handle for the key. Optionally, you may choose the alias.

---> keytoken

  • Request

  • Response

  • Method — POST
  • Path — /user/keys
  • Body — application/json
{
  "handle": "{key}"
}
2

Get the API key

Get the details of an existing API key to obtain the long-lived token associated with it. Skip this step if you have just created the API key. See the API reference.

<--- key

---> token

  • Request

  • Response

  • Method — GET
  • Path — /user/keys/{key}
3

Authenticate with the token

Add the token as a bearer token in the Authorization header. Most API endpoints require you to perform this step to authenticate yourself. See the API reference.

The token will continue to authenticate requests until its API key is deleted.

<--- token

---> ✦ authentication

  • Requests requiring authentication

  • Headers
Authorization: Bearer {token}

Validations

1

Validate your user details

To validate that authentication using your API keys is working, get your user details with the long-lived API key token you have obtained. See the API reference.

  • Request

  • Response

  • Method — GET
  • Path — /user