Authentication

GenieOS uses bearer authentication on every request. There are no sessions, no cookies, and no per-call signing — just an Authorization header. Scopes ride on the key itself; rotation is one click.

Authorization: Bearer gos_live_8a72c0e1...

Key flavours

A key always belongs to a single workspace. There is no concept of a multi-workspace key — if you operate several workspaces, mint one per workspace.

Scopes

Each key carries a set of scopes that bound what it can do. Scopes are additive — a key with templates:read and templates:send can read and send, but cannot create or modify templates.

The dashboard exposes presets — Read, Author, Send, Full — that compose these for you. Send and Full include organic social publish (social:posts:publish).

Generating a key

# Create the key at app.genieos.pro → Settings → API keys, then:
genie login
# or headless:
export GENIEOS_API_KEY=gos_live_...
genie keys list
genie whoami

Verifying authentication

A trivial smoke test:

curl -s https://api.genieos.pro/v1/workspace \
  -H "Authorization: Bearer $GENIEOS_API_KEY" \
  | jq .

A successful call returns the workspace document. Failures use the standard error envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key revoked or never issued.",
    "request_id": "req_01JABC..."
  }
}

Rotation

Keys can be rotated without downtime. The flow:

1. Create a new key with the same scopes; deploy it alongside the old one.
2. Verify production traffic on the new key (the dashboard shows last-used per key).
3. Click Revoke on the old key. Revocation is instant — the API rejects the old key on the next request.

For SDK-based integrations the SDK reads GENIEOS_API_KEY at startup, so a rolling deploy is enough. For long-lived workers, signal them to re-read the env or restart.

Storing keys safely

• Use a secrets manager (Doppler, Vault, AWS Secrets Manager, Google Secret Manager, GitHub/GitLab Secrets) — not committed .env files.
• Scope keys narrowly. A worker that only sends mail should hold a key with templates:send and nothing else.
• Per-environment keys. One per dev / staging / production. Never reuse a production key in a sandbox-shaped place.
• Watch the audit log. Every authenticated request lands in audit.log with key_id so you can correlate suspicious activity.

What\u2019s next

• Send your first request: Quickstart.
• Understand the safety net under retries: Idempotency.
• Hand authentication off to your AI editor: MCP.