Skip to main content
The Origami API uses API keys for authentication. The same key works on v3, v2, and v1. Every key is parent-wide: it belongs to your parent (agency) organization and can act on the parent or any of its projects. 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. 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.

​
Projects and the x-origami-project header

Because 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 is 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.