Getting started

Authentication

Get a key, then send it on every request.

LoreOS has two key paths:

  • Demo sandbox key — no signup, short-lived, and capped. Use it for local copy-paste testing and coding-agent quickstarts.
  • Invite key — persistent app key for real products and deployed services. Email daniel@contxts.io with a one-line note about what you’re building. We provision your app and send you a key.

No-key testing (demo sandbox key)

The demo sandbox key is the no-key path. POST /v1/demo/sandbox-key takes no auth and, when public issuance is enabled, returns a short-lived, capped sandbox key you can use to run the real quickstart locally:

$export LOREOS_KEY="$(curl -sS -X POST https://api.loreos.app/v1/demo/sandbox-key \
>  | jq -r '.data.api_key')"
$export LOREOS_BASE="https://api.loreos.app"

Demo keys are short-lived and capped. The exact caps (defaults shown; an operator can tune them, but these are the deployed values):

  • one sandbox app — the key is bound to a fresh isolated sandbox tenant + app;
  • three characters (POST /v1/characters past the third → 403 demo_quota_exceeded);
  • five sessions (past the fifth → 403 demo_quota_exceeded);
  • sixty user messages total (the 61st → 403 demo_quota_exceeded);
  • 1,200 characters per message (longer → 413 demo_input_too_large);
  • no image generation — image probes and inventory generation are blocked (403 demo_key_surface_disabled), and the key’s hard credit cap blocks metered work before any provider call regardless;
  • no managed Telegram and no webhook delivery (403 demo_key_surface_disabled);
  • no budget changes, no app creation, and no extra key issuance (403 demo_key_surface_disabled);
  • auto-expires (~24 hours) — every demo key carries an expiry and stops working after it (403 api_key_expired).

Demo keys are designed for local testing only. Do not deploy a demo key as production auth because it expires automatically and intentionally blocks product surfaces such as images, Telegram, webhooks, and additional key issuance.

Issuance is feature-flagged and rate-limited. This route is gated behind abuse controls and may be paused. Handle these responses:

  • 429 demo_sandbox_rate_limited — issuance rate limit reached. Issuance is capped per client (by default a few keys per IP and per fingerprint within a rolling ~1-hour window); the fix field tells you roughly how long to wait. Back off and retry after the window — do not loop-mint demo keys.
  • 503 demo_sandbox_disabled — public issuance is paused (maintenance or abuse controls). This is not transient from your side; use an invite key instead. Invite keys always work.

We do not publish a shared public LOREOS_KEY because LoreOS keys can create state and trigger metered model work.

The demo now fits a real multi-turn try — three characters, sixty messages, and a day-long TTL are enough to feel reply latency, the async event log (via polling), and reply quality across a few conversations. But for image generation, webhook/Telegram delivery, or a repeated eval loop, mint a persistent staging key. A demo key can’t generate images or use managed delivery, and re-minting one per run trips the issuance 429. Mint a durable key once — POST /v1/apps → POST /v1/api-keys (requires an existing key for your tenant, i.e. your invite key; a demo key cannot create apps or issue keys) — and reuse it. See Staging and evaluation.

Use your key

Send the key as a Bearer token on every request, against the base URL https://api.loreos.app:

$curl https://api.loreos.app/v1/me \
>  -H "Authorization: Bearer $LOREOS_KEY"

GET /v1/me returns the app your key resolves to — the quickest way to confirm that a demo or invite key works before you build anything else.

Keep keys safe

  • Treat keys like passwords — keep them server-side. Never ship a key in a browser or mobile app.
  • Each key is scoped to a single app; everything you create is isolated to that app.
  • Need to rotate a compromised key? Email us and we’ll reissue.