Authentication

To use the API, you must authenticate using your user credentials or an API Key. This key securely identifies each user or application making requests to the service.

The login endpoint, using your user credentials, provides a valid token for performing all available operations.

For more stable or long-term use, it is recommended to create an API Key with a configurable expiration date.

Generating API Keys

API Keys can be generated from the platform's web panel, in the corresponding section. They can also be created using a dedicated endpoint within the REST API itself.

To do this, you must first log in with your user credentials. This is done by sending a POST request to the endpoint /api/auth/login

curl -X 'POST' \
  'https://fair-dev.gradiant.org/api/auth/login' \
  -H 'accept: application/json' \
  -H 'user-agent: custom' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={USERNAME}&password={PASSWORD}'

This will return the temporary token:

{
    "access_token":"{ACCESS_TOKEN}",
    "token_type":"bearer",
    "refresh_token":"{REFRESH_TOKEN}",
    "accepted_terms_of_service":true
}

With this, you can now make any request. To create an API key, use the /api/v1/api-keys endpoint:

curl -X 'POST' \
  'https://fair-dev.gradiant.org/api/v1/api-keys' \
  -H 'accept: application/json' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "MY_API_TOKEN_1",
  "expiration_days": 0
}'

An expiration time of 0 indicates that the API key will not expire automatically. Nos devolverá la API KEY:

{
  "id": "{KEY_ID}",
  "name": "MY_API_TOKEN_1",
  "key_hash": "{API_KEY}",
  "created": "2026-03-16T11:39:32",
  "expires_at": null
}

Each user can create one or more keys according to their needs (for example, to separate development and production environments).

It is recommended to store the API Key securely and not include it directly in public source code or shared repositories.

Using the API Key in Requests

All API requests must include the API Key in the corresponding HTTP header. Without this header, the server will reject the request with an authentication error.

Generic Example:

Authorization: Bearer <API_KEY>

The API key must be sent in all requests, regardless of the endpoint used.

Security Best Practices

• Do not share API keys between users.

• Immediately revoke a key if compromise is suspected.

• Use different keys for different environments.

• Avoid exposing the key in frontend applications; instead, route requests through a secure backend.