Authentication

The API supports two authentication methods:

• An OAuth2 token obtained through user login.
• An API Key sent in the X-API-Key header.

API Keys are recommended for server-to-server integrations. They are associated with the user who creates them and inherit that user's permissions and usage limits.

User token

The login endpoint provides a temporary token for the operations available to the user. The login endpoint is outside the API base URL:

/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}'

The response contains the temporary token:

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

Use the token as a bearer token:

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

To create an API Key, use POST /api/v2/api-keys with the user token. The complete key management guide is available in API Key Management. API Key creation, lookup, and management cannot be performed with another 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
}'

The response includes the key identifier and the value you must store for later use:

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

The expiration_days field is optional. Use a value that matches your integration's security policy; non-expiring keys should be reserved for cases where they are strictly necessary.

Each user can create multiple keys, for example, one for each environment or application.

Store the API Key securely and never include it directly in public source code or shared repositories.

Using an API Key in requests

Authenticated resource requests using an API Key must include the X-API-Key header. The API base URL is:

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

Example:

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"

An API Key can upload and query files created with that key, create and query its runs, and retrieve its results. It cannot retrieve user information (/users/me) or manage API Keys.

Security best practices

• Do not share API Keys between users.

• Revoke a key immediately if you suspect it has been compromised.

• Use different keys for different environments.

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