Authentication

Our API provides flexible authentication options to suit different use cases. This section explains how to authenticate using credentials, Two-Factor Authentication (2FA), or ussing the Access Tokens.

Authenticate with Username and Password

Use this method to authenticate with a user's credentials (username and password). Depending on whether 2FA is enabled, the process may require an additional step.

:::info[API Key required]
All API requests must include the API key in the headers. This is required for all endpoints, regardless of the authentication method used.

# Headers Example
x-api-key: your-api-key

:::

1. Send a `POST` request to `/auth/sign_in` with the username and password. 2. The server responds with an authentication token, which must be included in the `Authorization` header for subsequent requests.

  ### Example Request
  ```
  POST /auth/sign_in
  Content-Type: application/json

    {
      "username": "your_username",
      "password": "your_password"
    }
  ```
  
  ### Example Response
  ```
  {
      "token": "your-auth-token",
  }
  ```
  
  ### Authorization Header for Subsequent Requests:
  ```
  Authorization: Bearer your-auth-token
  ```

If the user has 2FA enabled, the process involves two steps:

Step 1: Initial Authentication

Send a POST request to /auth/sign_in with the username and password. If the credentials are valid, the server will respond with an otp_session_state.

  #### Example Request
  ```
  POST /auth/sign_in
  Content-Type: application/json

    {
      "username": "your_username",
      "password": "your_password"
    }
  ```
  
  #### Example Response
  ```
  {
      "otp_session_state": "session-token"
  }
  ```
  
  ### Step 2: Verify OTP

Send another POST request to /auth/sign_in with otp_attempt (the OTP received via SMS or an authentication app), and otp_session_state.

  #### Example Request
  ```
  POST /auth/sign_in
  Content-Type: application/json

    {
      "otp_attempt": "123456",
      "otp_session_state": "session-token"
    }
  ```
  
  #### Example Response
  ```
  {
      "token": "your-auth-token"
  }
  ```

Authentication with Access Token

The Access Token method allows long-term authentication without requiring a login for each session. This is ideal for applications or scripts that need to interact with the API regularly.

Generate an Access Token

Access Tokens can be generated in the My Settings section of the portal or by using the PUT /v2/user/generate_access_token endpoint. Once generated, the token does not expire and can be used for all API requests.

Use an Access Token

Include the token in the Authorization header of your requests:

Authorization: Basic your-access-token

Last modified: 10 days ago