Authentication

Authentication in the API

The API uses JWT (JSON Web Token) with a Bearer authentication scheme to securely authenticate requests. This method ensures that only authorized users can access the API and perform actions. Each request must include a valid token in the Authorization header.

How JWT Authentication Works

1. Generate a Long-Living Token (Private Token): Once you have the short-living token, you can create a long-living private token that’s ideal for backend applications or automated processes. This token is generally stored in your server configuration and used for repeated API requests. This token expires on a custom-set time. Authentication

2. Token Expiry: Long-living tokens have an expiration time, meaning they are valid only for a set duration. You can specify an expiration time when generating long-living tokens, but remember to follow security best practices, such as setting the lowest expiration time possible and rotating tokens regularly.

Sending the JWT Token

Once you have the JWT token (whether short-living or long-living), you must include it in the Authorization header of every API request. The format is as follows:

Authorization: Bearer {your_token_here}

Example request:

GET /api/v1/companies/{company_id}/datasets/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

In this example, the Authorization header contains the keyword Bearer, followed by the JWT token.

---

Token Management and Security Best Practices

• UI Management: check Authentication

• Token Expiration: Always be aware of the expiration time for your tokens and renew them as needed to ensure uninterrupted access. Expiration time can be seen in the API keys section. Expiration time can be set only on creation.

• Rotate Tokens Regularly: Even though tokens are secure, it’s a good practice to rotate them periodically. This minimizes the risk of misuse in case a token is compromised. To rotate a token you need:

  • create a new private token in SaaS: Create API Key.

  • set your code to use new token.

  • revoke old private token in SaaS: Delete API Key.

• Handle Expired Tokens: If the token is expired, the API will return a 401 Unauthorized error. When this happens, you’ll need to log in again or renew the token to get a new one.

• Token Revocation: If a token needs to be invalidated (e.g., if credentials are compromised), make sure to revoke or stop using the token as soon as possible. API Method

Manage API Key via UI

API Key Management is available only for clients on the following plans: Professional and Professional Unlimited.

Create API Key

1. Hover on your user name in the bottom-left corner.

2. Navigate to the API Keys section.

   
3. Click the Create new API key button in the top-right corner.

4. Name your key and select the expiration time.

   
5. Copy our API key. Keep it in the secure and safe space. Make sure to also copy Company ID. You will need this to use API.

Delete API Key

Please note that API key deletion is permanent, this action can not be reversed.

1. Hover on your user name in the bottom-left corner.

2. Navigate to the API Keys section.

3. Find the key you want to delete.

4. Click on the ... button and then click Delete.

5. Confirm deletion.

Example Error Response for Invalid or Expired Token

If you try to access a resource with an invalid or expired token, the API will return an error response:

{
  "type": "client_error",
  "errors": [
    {
      "code": "invalid_token",
      "detail": "The provided token is expired or invalid.",
      "attr": null,
      "extra": null
    }
  ]
}

In this case, the code indicates that the token is invalid, and the detail explains that it’s either expired or incorrect.