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. Login to Get a Short-Living Token: When a user logs in, they receive a short-living token by providing their account credentials (email and password). This token is used to authenticate subsequent requests, including creating a long-living private token. This token always expires in 1 hour. API Link

2. 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. API Link

3. Token Expiry: Both short-living and long-living tokens have an expiration time, meaning they are valid only for a set duration. Short-living token always expires in 1 hour. 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: Unavailable at the moment.

• List all created tokens: Use this method: API Link.

• 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 private tokens list response (API Link). Expiration time can be set only on creation. There is no default value for expiration.

• 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 API Link

  • set your code to use new token

  • revoke old private token in SaaS API Link

• 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

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.