API Keys

API keys are long-lived credentials for server-to-server integrations. Use them to authenticate queries, upload documents, and access your organization's data from your own applications.

Creating an API key

Create API keys from the dashboard (Settings → API Keys → New Key), or programmatically using a JWT access token. The JWT-based flow is useful for automation and CI/CD pipelines that provision keys per environment.

All API key management endpoints require a JWT access token obtained from POST https://api.getegret.com/auth/jwt/create/.

List API keys

GET https://api.getegret.com/v1/billings/api-keys/
Authorization: Bearer <jwt_access_token>

[
  {
    "id": "50b4faab-c0c8-48e0-95e8-ca4deb61d968",
    "name": "Egret Dev Key",
    "key_prefix": "egret_9NO11FMNDj0RXk",
    "is_active": true,
    "last_used_at": null,
    "created_at": "2026-03-16T21:40:14.228985Z",
    "expires_at": "2026-04-15T07:00:00Z"
  }
]

The list never returns the full key value — only the key_prefix for identification.

Create an API key

POST https://api.getegret.com/v1/billings/api-keys/
Authorization: Bearer <jwt_access_token>
Content-Type: application/json

{
  "name": "Egret Dev API Key"
}

{
  "id": "9cb650b6-3ac5-44a0-8b72-2250d5f620f6",
  "name": "Egret Dev API Key",
  "key_prefix": "egret_tX1g3XB143QVaf",
  "is_active": true,
  "last_used_at": null,
  "created_at": "2026-03-25T22:08:24.339988Z",
  "expires_at": null,
  "key": "egret_tX1g3XB143QVaf..."
}

The full key value is only returned once at creation time. Copy and store it securely — it cannot be retrieved again. If lost, rotate the key to generate a new one.

Set or clear expiration

Use PATCH to add or remove an expiration date on an existing key.

PATCH https://api.getegret.com/v1/billings/api-keys/{key_id}/update/
Authorization: Bearer <jwt_access_token>
Content-Type: application/json

{
  "expires_at": "2027-03-11T00:00:00Z"
}

Pass "expires_at": null to remove the expiration and make the key non-expiring.

Rotate an API key

Rotating a key invalidates the existing key and issues a new one with the same name and settings. Use this if a key is compromised or as part of a regular rotation policy.

POST https://api.getegret.com/v1/billings/api-keys/{key_id}/rotate/
Authorization: Bearer <jwt_access_token>

{
  "id": "daa7ac4f-7012-4138-878c-487f4cdfb212",
  "name": "Egret Dev API Key",
  "key_prefix": "egret_EK_jHr78GY7jMx",
  "is_active": true,
  "last_used_at": null,
  "created_at": "2026-03-25T22:10:44.769620Z",
  "expires_at": "2027-03-11T00:00:00Z",
  "key": "egret_EK_jHr78GY7jMxHRPWG...",
  "rotated_from": "9cb650b6-3ac5-44a0-8b72-2250d5f620f6"
}

The response includes rotated_from — the ID of the key that was replaced. The full key value is shown once, same as creation.

Using an API key

Pass the full key value in the Authorization header on any query or API request:

Authorization: Bearer egret_EK_jHr78GY7jMx...

Alternatively, use the X-API-Key header:

X-API-Key: egret_EK_jHr78GY7jMx...

Invalid or expired key

Using an inactive, expired, or revoked key returns 401 Unauthorized:

{
  "detail": "Invalid or expired API key. Check that the key is active and has not expired."
}