Skip to main content
The Origami API uses API keys for authentication. The same key works on v3, v2, and v1 unless its access is limited or it is bound to one project (below). An org-wide key is parent-wide: it belongs to your parent (agency) organization and can act on the parent or any of its projects. A key bound to one project works only on v3. v3 keys also carry a role: member (default for new keys) or admin. Existing keys were backfilled to admin. Admin-gated Account operations (webhook CRUD, key create/revoke, domain purchase) return 403 for member keys.

Creating an API key

  1. Go to Settings → Developers in the Origami app
  2. Click Create API key
  3. Give it a descriptive name (e.g. “n8n integration”, “CRM sync”)
  4. Choose its access. Full API (on by default) covers v1, v2 and v3. Autopilot and Budget unlock the Autopilot API.
  5. Copy the key immediately — it’s shown only once
API keys follow the format:
The og_live_ prefix makes keys identifiable in leaked-credential scans (GitHub secret scanning, GitGuardian, etc.).

Using your API key

Pass the key in the Authorization header as a Bearer token:
Every request must include this header. Requests without a valid key return 401 UNAUTHORIZED. Organizations whose plan doesn’t include API access return 402 with code: "SUBSCRIPTION_REQUIRED" — upgrade to a plan with API access. A key with Autopilot or Budget access but not Full API returns 403 with code: "FORBIDDEN" on v1, v2 and v3; turn on Full API for that key to call them. A key bound to one project returns 403 with code: "FORBIDDEN" on v1 and v2. Use v3 for that key.

Projects and the x-origami-project header

Because org-wide keys are parent-wide, you choose which org a request acts on with the x-origami-project header:
  • Omit it to act on the parent org.
  • Send x-origami-project: <project_id> to scope the request to that project (a child org).
On v3 the header applies to Leads, Send, Jobs, and — within Account — chats and exclusion lists. It is ignored by project management, org reads, senders, domains, mailboxes, webhooks, and API-key routes. On v2 two surfaces ignore it: /projects/* always manages projects from the parent, and /account and /account/* are always parent-scoped. The header fails closed. A malformed id returns 400 VALIDATION_ERROR; an unknown, cross-parent, or deleted project returns 404 PROJECT_NOT_FOUND. The plan gate and rate limits stay keyed to the parent, and the concurrent-agent pool is shared across the whole parent. Credits spent inside a project draw on the parent’s shared wallet, subject to the project’s optional monthly credit budget cap and its enforcement mode ("hard" blocks spend at the cap; "soft" tracks without blocking).
Manage projects with the Projects endpoints. v2 tenancy is documented under objects and relationships.

Key management

  • Multiple keys: Create as many keys as you need — one per integration is recommended.
  • Revocation: Revoke a key anytime from the API keys settings page. Revoked keys return 401 immediately.
  • Rotation: To rotate a key, create a new one, update your integration, then revoke the old one.
  • Identification: The UI shows the last 4 characters of each key.

Security best practices

Never commit API keys to source control. Use environment variables or a secrets manager.
  • Store keys in environment variables (ORIGAMI_API_KEY) or a secrets manager
  • Use separate keys for development and production
  • Revoke keys immediately if they may have been exposed
  • Review the API keys settings page periodically and remove unused keys

Rate limits

Limits apply per client IP and per organization. Both stay keyed to the parent org, even when a request is scoped to a project. The scarce resource for agent work is the concurrent-run slot — exceeding it returns 429 with code: "CONCURRENT_LIMIT_EXCEEDED" and a Retry-After header. When rate-limited, the API returns 429 Too Many Requests. Responses carry usage headers so you can track quota proactively: v3 also exposes per-bucket standing at GET /account/rate-limits (org / expensive / insert / ip). Traffic on v1, v2, and v3 shares the same underlying org allowance.
Rate limits use a sliding window. If you hit the limit, honor Retry-After rather than retrying immediately.