Authentication

Egret supports two authentication methods: JWT tokens for browser/UI clients and API keys for server-to-server integrations.

JWT (Browser clients)

Obtain a short-lived access token and a long-lived refresh token by logging in:

POST /auth/jwt/create/
Content-Type: application/json

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

Response:

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

Token	Lifetime	Used for
`access`	5 minutes	All API requests
`refresh`	30 days	Obtaining new access tokens

Use the access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

API Keys (Server-to-server)

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

Authorization: Api-Key ek_live_abc123...

Create API keys from the dashboard under Settings → API Keys, or via the API Keys endpoint.

Scopes

API keys can be created with restricted scopes:

Scope	Access
`read`	Read-only access to queries, sessions, and domains
`write`	Full read/write access
`admin`	Organization management, billing, and user administration

Next steps

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