Authentication

Epithre uses API keys for programmatic API access (/v1/*) and JWT sessions for browser-based dashboard access (/dashboard/*). You'll mostly care about API keys.

API keys

Format: esk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (live) or esk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (test).

• esk_live_* is the default. Real billing applies.
• esk_test_* is for sandbox / CI. Same endpoints, same behavior, but billed to a separate ledger so test usage doesn't pollute your production cost reports. Created via the dashboard with "Test key" checked.

Send your key in the Authorization header on every /v1/* request:

POST /v1/chat/completions HTTP/1.1
Host: api.epithre.com
Authorization: Bearer esk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{...}

The Python openai SDK handles this automatically when you set api_key.

Creating a key

1. Sign in at platform.epithre.com.
2. Navigate to API Keys.
3. Enter a descriptive name (e.g. production-api, staging-batch-worker, local-dev-laptop).
4. Optionally check "Test key" for a sandbox key.
5. Click Create key.

The full key is shown exactly once. We store only the SHA-256 hash, so we can never recover the original. Copy it immediately and store in your secret manager.

Credit balance vs per-key limits

Credit balance is account-level. One pool per Epithre account, drained by every key you create. Top up once, all your keys can spend from it. When the pool hits Rp0, every key returns 402 until you top up.

Per-key limits below are independent caps on each key's traffic and spend rate. They do not partition the balance:

Raise any of these in the dashboard at any time. They take effect within a few seconds.

Best practices

• One key per app / environment. Production server gets its own key. Staging gets its own. Local development gets its own. When something leaks, you only revoke one.
• Store keys in environment variables, secret managers, or Vault. Never commit to git.
• Set spending caps per key. If a runaway loop hits production, the cap saves you from the worst.
• Rotate quarterly or after team membership changes. Create a new key, deploy it, revoke the old one a few days later.
• Use test keys for CI. They report against a separate billing ledger, so you can see clearly which spend is real vs. CI.

Revoking a key

If you suspect a key has leaked (committed to public repo, shown in a screenshot, etc), revoke it immediately:

1. Dashboard -> API Keys
2. Find the row, click Revoke

Revocation propagates within 30 seconds. After that, every request using the revoked key returns HTTP 401.

JWT sessions (dashboard)

When you sign in at platform.epithre.com, you get a 24-hour JWT stored in your browser's localStorage. Used only for dashboard-internal endpoints (/dashboard/*, /admin/*). Not interchangeable with API keys.

You generally don't need to think about these unless you're building a third-party tool that drives the dashboard programmatically. We don't currently document the JWT endpoints externally; email us if you have that use case.

Scopes (future)

API keys carry a scopes array, currently always ["*"] (full access). The schema supports per-endpoint scope restrictions; the dashboard UI to set them is on the roadmap. If you need scoped keys today (e.g. an embed-only key for a partner), email us and we'll cut one server-side.

Failure modes

Full error catalogue: error handling.