Gestión de API Keys

Una API Key identifica a una aplicación o integración sin tener que almacenar las credenciales de un usuario. La clave se asocia al usuario que la crea, por lo que las operaciones que puede realizar están sujetas a los permisos, suscripción y límites de ese usuario.

Crear una clave

Las API Keys se crean, consultan y administran únicamente con las credenciales del usuario. Pueden crearse accediendo al panel web de la plataforma o mediante la API (con POST /api/v2/api-keys) utilizando un token obtenido mediante el login.

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

curl -X POST "$API_URL/api-keys" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "produccion",
    "expiration_days": 90
  }'

El cuerpo requiere name. expiration_days es opcional. El valor 0 indica que la clave no caduca. Guarda el valor de key_hash de la respuesta como secreto y conserva el id para gestionar la clave después.

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

Usar una clave

Envía la clave en la cabecera X-API-Key junto con la base URL de la API:

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"

Múltiples endpoints de la API requieren el uso de credenciales de usuario y devuelven 401 Unauthorized si se intenta acceder con una API Key.

Una API Key solo puede operar sobre los recursos que se hayan creado utilizando esa misma clave. Permite el siguiente flujo:

1. POST /files para subir el fichero.
2. GET /files para listar los ficheros subidos con esa clave.
3. GET /files/{file_id} para consultar un fichero subido con esa clave.
4. POST /runs para iniciar una ejecución sobre uno de esos ficheros.
5. GET /runs para listar las ejecuciones creadas con esa clave.
6. GET /runs/{run_id} para consultar el estado de una ejecución propia.
7. GET /runs/{run_id}/results para listar los resultados de una ejecución propia.
8. GET /runs/{run_id}/results/{run_result_id} para consultar un resultado concreto.

También puede descargar un fichero propio con GET /files/{file_id}/download y los archivos asociados a un resultado con GET /runs/{run_id}/results/{run_result_id}/files/{file_url}.

También puede eliminar un fichero subido con esa misma API Key mediante DELETE /files/{file_id}. Las API Keys no pueden gestionar comentarios de ficheros.

curl -X DELETE "$API_URL/files/{FILE_ID}" \
  -H "X-API-Key: $API_KEY"

Las API Keys no se pueden utilizar para crear, listar, consultar, actualizar, revocar, activar ni eliminar otras API Keys.

Consultar claves y uso

Las operaciones de administración de claves requieren un token de usuario. Lista las claves del usuario con GET /api/v2/api-keys:

curl "$API_URL/api-keys" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Para incluir el número de ficheros y ejecuciones asociados a cada clave, añade include=usage:

curl "$API_URL/api-keys?include=usage" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

También puedes consultar una clave concreta con GET /api/v2/api-keys/{api_key_id} usando Authorization: Bearer $ACCESS_TOKEN. El parámetro include=usage funciona igualmente en este endpoint.

Los datos de una clave pueden incluir:

• id: identificador usado en las operaciones de gestión.
• name: nombre descriptivo.
• created_at: fecha de creación.
• expires_at: fecha de caducidad, si existe.
• revoked_at: fecha de revocación, si la clave fue revocada.
• last_usage_at: último uso registrado.
• usage.files y usage.runs: uso asociado cuando se solicita include=usage.

Actualizar, revocar y eliminar

Puedes cambiar el nombre o la caducidad con PATCH /api/v2/api-keys/{api_key_id}:

curl -X PATCH "$API_URL/api-keys/{KEY_ID}" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "produccion-renovada",
    "expiration_days": 180
  }'

Revoca temporalmente una clave con:

curl -X PATCH "$API_URL/api-keys/{KEY_ID}/revoke" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Una clave revocada se puede volver a activar con PATCH /api/v2/api-keys/{api_key_id}/activate:

curl -X PATCH "$API_URL/api-keys/{KEY_ID}/activate" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Para eliminarla definitivamente utiliza DELETE /api/v2/api-keys/{api_key_id}:

curl -X DELETE "$API_URL/api-keys/{KEY_ID}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Recomendaciones

• Guarda la clave en un gestor de secretos o variable de entorno, nunca en el código fuente.
• Usa una clave diferente para cada aplicación o entorno.
• No expongas una API Key en código JavaScript que se ejecute en el navegador.
• Revoca la clave inmediatamente si se filtra y genera una nueva.
• Elimina las claves que ya no se utilicen y establece una caducidad cuando sea posible.