API Key Management

An API Key identifies an application or integration without storing a user's credentials. The key is associated with the user who creates it, so the operations it can perform are subject to that user's permissions, subscription, and usage limits.

Creating a key

API Keys are created, queried, and managed only with user credentials. They can be created through the platform's web panel or through the API with POST /api/v2/api-keys, using a token obtained through 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": "production",
    "expiration_days": 90
  }'

The body requires name. expiration_days is optional. A value of 0 means that the key does not expire. Store the key_hash value from the response as a secret and keep the id to manage the key later.

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

Using a key

Send the key in the X-API-Key header together with the API base URL:

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"

Several API endpoints require user credentials and return 401 Unauthorized when accessed with an API Key.

An API Key can only operate on resources created using that same key. It supports this workflow:

1. POST /files to upload a file.
2. GET /files to list files uploaded with that key.
3. GET /files/{file_id} to query a file uploaded with that key.
4. POST /runs to start a run on one of those files.
5. GET /runs to list runs created with that key.
6. GET /runs/{run_id} to query the status of one of its runs.
7. GET /runs/{run_id}/results to list the results of one of its runs.
8. GET /runs/{run_id}/results/{run_result_id} to query a specific result.

It can also download one of its files with GET /files/{file_id}/download and files associated with a result using GET /runs/{run_id}/results/{run_result_id}/files/{file_url}.

It is also possible to delete a file uploaded with that same API Key using DELETE /files/{file_id}. API Keys cannot manage file comments.

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

API Keys cannot be used to create, list, query, update, revoke, activate, or delete other API Keys.

Querying keys and usage

Key management operations require a user token. List the user's keys with GET /api/v2/api-keys:

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

To include the number of files and runs associated with each key, add include=usage:

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

You can also query a specific key with GET /api/v2/api-keys/{api_key_id} using Authorization: Bearer $ACCESS_TOKEN. The include=usage parameter works on this endpoint as well.

Key data may include:

• id: identifier used for management operations.
• name: descriptive name.
• created_at: creation date.
• expires_at: expiration date, if any.
• revoked_at: revocation date, if the key was revoked.
• last_usage_at: last recorded use.
• usage.files and usage.runs: associated usage when include=usage is requested.

Updating, revoking, and deleting

You can change the name or expiration with 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": "renewed-production",
    "expiration_days": 180
  }'

Temporarily revoke a key with:

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

A revoked key can be activated again with 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"

To delete it permanently, use DELETE /api/v2/api-keys/{api_key_id}:

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

Recommendations

• Store the key in a secrets manager or environment variable, never in source code.
• Use a different key for each application or environment.
• Do not expose an API Key in JavaScript code running in the browser.
• Revoke the key immediately if it is leaked and generate a new one.
• Delete keys that are no longer used and set an expiration whenever possible.