Saltar al contenido principal

Autenticación

Para utilizar la API es necesario autenticarse mediante las credenciales de usuario o una API Key. Esta clave permite identificar de forma segura a cada usuario o aplicación que realiza solicitudes al servicio.

El endpoint de login, mediante las credenciales de usuario proporciona un token valido para realizar todas las operaciones disponibles para el usuario. Para un uso más estable o prolongado en el tiempo se recomienda crear una API Key, de caducidad configurable.

Generación de API Keys​

Las API Keys pueden generarse desde el panel web de la plataforma, en la sección correspondiente. También es posible crearlas mediante un endpoint dedicado en la propia API REST.

Para ello es necesario hacer un primer login con las credenciales de usuario. Esto se hace mediante una petición POST al 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}'

Nos devolverá el token temporal:

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

Con este ya es posible realizar cualquier petición. Para crear una API KEY se utiliza el 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
}'

Un tiempo de expiración de 0 indica que la API KEY no caducará automaticamente. 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
}

Cada usuario puede crear una o varias claves según sus necesidades (por ejemplo, separar entornos de desarrollo y producción).

Se recomienda almacenar la API Key de forma segura y no incluirla directamente en código fuente público o repositorios compartidos.

Uso de la API Key en las peticiones​

Todas las solicitudes a la API deben incluir la API Key en la cabecera HTTP correspondiente. Sin esta cabecera, el servidor rechazará la petición con un error de autenticación.

Ejemplo genérico:

Authorization: Bearer <API_KEY>

La API Key debe enviarse en todas las peticiones, independientemente del endpoint utilizado.

Buenas prácticas de seguridad​

  • No compartir API Keys entre usuarios.

  • Revocar inmediatamente una clave si se sospecha compromiso.

  • Utilizar claves distintas para distintos entornos.

  • Evitar exponer la clave en aplicaciones frontend; en su lugar, canalizar las peticiones a través de un backend seguro.