Saltar al contenido principal

Autenticación

La API admite dos métodos de autenticación:

  • Un token OAuth2 obtenido mediante el login de usuario.
  • Una API Key enviada en la cabecera X-API-Key.

Las API Keys son la opción recomendada para integraciones de servidor a servidor. Se asocian al usuario que las crea y heredan sus permisos y límites de uso.

Token de usuario​

El endpoint de login proporciona un token temporal para realizar las operaciones disponibles para el usuario. El endpoint de login está fuera de la base URL de la API:

/api/auth/login
curl -X 'POST' \
  'https://veraquo.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
}

Utiliza el token como un bearer token:

curl 'https://veraquo.gradiant.org/api/v2/users/me' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'

Para crear una API Key utiliza POST /api/v2/api-keys con el token de usuario. La gestión completa de las claves se describe en Gestión de API Keys. Las operaciones de creación, consulta y administración de API Keys no se pueden realizar con otra API Key.

curl -X 'POST' \
  'https://veraquo.gradiant.org/api/v2/api-keys' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-integration",
  "expiration_days": 90
}'

La respuesta incluye el identificador de la clave y el valor que debes guardar para usarlo posteriormente:

{
  "id": "{KEY_ID}",
  "name": "my-integration",
  "key_hash": "{API_KEY}",
  "created_at": "2026-03-16T11:39:32Z",
  "expires_at": "2026-06-14T11:39:32Z"
}

El campo expiration_days es opcional. Usa el valor que corresponda a la política de seguridad de tu integración; una clave sin fecha de expiración debe reservarse para los casos en los que sea estrictamente necesaria.

Cada usuario puede crear varias claves según sus necesidades, por ejemplo, una por entorno o aplicació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​

Las solicitudes de recursos autenticadas con API Key deben incluirla en la cabecera X-API-Key. La base URL de la API es:

https://veraquo.gradiant.org/api/v2

Ejemplo:

API_URL="https://veraquo.gradiant.org/api/v2"
API_KEY="{API_KEY}"

curl "$API_URL/files" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

La API Key puede utilizarse para subir y consultar los ficheros creados con ella, crear y consultar sus ejecuciones, y recuperar sus resultados. No puede utilizarse para recuperar información del usuario (/users/me) ni para gestionar API Keys.

Buenas prácticas de seguridad​

  • No compartir API Keys entre usuarios.

  • Revocar inmediatamente una clave si se sospecha que esta se ha comprometido.

  • 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.