Authentication

Egret supports two authentication methods: JWT tokens for browser/UI clients and API keys for server-to-server integrations. Both give access to the same capabilities — the choice depends on your use case.

JWT (Browser clients)

Obtain a short-lived access token and a long-lived refresh token by posting your credentials:

POST https://api.getegret.com/auth/jwt/create/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

Response:

{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Include the access token on every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Refreshing the access token

When the access token expires, exchange the refresh token for a new one:

POST https://api.getegret.com/auth/jwt/refresh/
Content-Type: application/json

{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

API Keys (Server-to-server)

API keys are long-lived credentials suited for scripts, integrations, CI pipelines, and server-to-server calls. They don't expire unless revoked or an explicit expires_at is set.

All API keys begin with the prefix egret_ and are passed as a Bearer token:

Authorization: Bearer egret_abc123...

The server distinguishes API keys from JWT tokens by prefix — egret_ tokens are processed as API keys; all others are passed to JWT processing.

Create and manage API keys from the dashboard under Settings → API Keys, or via the API Keys endpoint. The raw key is shown once at creation and cannot be retrieved again — store it securely.

What authenticated users can do

All authenticated users (via JWT or API key) can:

• Run queries against any active public domain
• Create and manage their own organisation
• Create and revoke their own API keys
• Upload documents to their organisation's private knowledge base
• Create and manage chat sessions

The following are restricted to platform administrators and cannot be performed by regular users or API keys:

• Creating, modifying, or deleting public domains and regions (e.g. business-continuity, us)
• Adding or removing documents from public domain knowledge bases

Next steps

• API Keys — Create and manage API keys
• Error Codes — Handle 401 and 403 responses