Authentication

Every authenticated API endpoint requires an Authorization: Bearer <token> header. The token is either a JWT (web session) or a personal API key (PAT). This article covers both.

The two token types

Both pass via the same header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn... # JWT
Authorization: Bearer nq-v1-Xk9mQ2pR7wT4vL8nB3sH6yJ1cF5dG0aZ... # PAT

The backend tries to validate as JWT first, falls back to PAT. You don't have to indicate which type you're sending.

When to use which

• In a browser session — JWT, automatically. The frontend handles it.
• In a script or backend — PAT. Don't try to mimic the sign-in flow; use a long-lived PAT instead.
• In CI/CD — PAT, stored as a secret in your CI provider.
• In a test suite — PAT for one test account, deleted between runs if needed.
• For your end users to call Nyquest from their accounts — they each create their own PAT. You don't share one.

One important behavioral difference

PAT requests are stateless — they do not appear in the web-UI chat history, do not run memory recall, and do not honor the x-nyquest-conversation header. JWT (browser) requests do all of those things.

This is the same pattern OpenAI, Anthropic, and Stripe use: APIs are for programs that manage their own state, web UIs are for humans whose conversations should be remembered. See API Overview → API key requests are stateless for the full picture.

Creating a PAT

POST /user/api-keys requires an authenticated account. A browser JWT or an existing full-account PAT can create a key:

curl -X POST https://api.nyquest.ai/user/api-keys \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'

Response (PAT shown ONCE — save it):

{
  "id": "abc-123-...",
  "key": "nq-v1-Xk9mQ2pR7wT4vL8nB3sH6yJ1cF5dG0aZ...",
  "key_prefix": "nq-v1-Xk9m",
  "name": "my-script",
  "created_at": "2026-04-30T..."
}

After this response you cannot retrieve the full key again. Listing PATs returns only key_prefix (the first 12 chars) for visual identification.

The web UI also lets you create PATs at Settings → API Keys → + Add Key. Same backend; just a friendlier interface.

Listing PATs

curl https://api.nyquest.ai/user/api-keys \
  -H "Authorization: Bearer <token>"

Returns array of {id, key_prefix, name, created_at} for each key on your account. No key field — keys are write-only-once.

Deleting a PAT

curl -X DELETE https://api.nyquest.ai/user/api-keys/<id> \
  -H "Authorization: Bearer <token>"

Immediate. The deleted PAT stops working on the next request. No grace period.

What a PAT can do

A PAT inherits the privileges of the user who created it. There is no scoping currently — every PAT can:

• Send chat completions
• Run agent goals
• Generate images / audio
• Read/write conversations, projects, artifacts
• Read billing info (but NOT trigger funding — that requires Stripe Checkout via the browser)
• Read/write BYOK providers and settings
• Manage other PATs (create, list, delete)

Per-PAT scoping (e.g. "this key can only call /v1/chat/completions, not delete things") is on the roadmap but not built. Treat each PAT like a full account credential.

Security best practices

• Store PATs as secrets. Never commit them to git. Use .env files (gitignored), env vars, or your platform's secret manager.
• One PAT per integration. When you delete a key, only that integration breaks. Easier than rotating a shared key.
• Name keys descriptively. "github-actions-prod" vs "my-laptop-test". You'll thank yourself later.
• Rotate periodically. Even though PATs don't expire, deleting and recreating every 6-12 months is a good hygiene baseline.
• Revoke immediately if leaked. Delete the key as soon as you suspect compromise. Recreate. Update wherever it was used.
• Use HTTPS only. Never send a PAT over HTTP. The platform only serves HTTPS, so this is enforced server-side, but watch for misconfigured clients.

What if a PAT is leaked?

If you suspect a PAT was leaked (committed to a public repo, pasted in chat, etc.):

1. Delete the PAT immediately. Settings → API Keys → trash icon, or DELETE /user/api-keys/<id>.
2. Audit recent activity. Open the More menu → Usage. If anything looks unauthorized, talk to a real human — we can refund and disable the affected account.
3. Create a new PAT with a new name (so you remember which integration it's for).
4. Update the integration with the new key.

Don't rely on an external scanner to catch this for you. Nyquest keys are not registered with GitHub's secret-scanning partner program, so a leaked key pushed to a public repository will not trigger a GitHub alert. If you want automated protection, add your own rule — match the literal prefix nq-v1- in your pre-commit hooks, CI secret scanning, and log redaction.

Edge cases

What if I've signed out but my JWT is still valid?

JWTs are valid for 8 hours from issuance. Signing out does NOT invalidate the JWT cryptographically — the platform's signing-out flow just clears it from your browser. If a JWT was leaked, it stays valid until expiry.

This is one reason PATs are preferred for scripts: deleting a PAT actually invalidates it server-side. JWTs can't be revoked individually.

What if my account is deleted while a PAT is in use?

Deleting your account (Settings → Account → Delete account) cascades to all PATs. They stop working immediately.

Can I share a PAT?

Technically yes (it's just a string). You shouldn't, because:

• Anyone with the PAT can do everything your account can do
• All activity attributes back to your account in our logs
• We can't tell if the request was from you or someone you shared with

For shared use cases, each person should have their own account and PAT.

Where to next

• Personal API Keys — deeper PAT management
• OpenAI-Compatible Chat — first usage example
• Endpoints Reference — full endpoint catalog
• Rate Limits and Quotas — what limits apply