Preview. The endpoints on this page are illustrative and are likely to change as they move toward general availability. Documentation is published in advance so you can start shaping your integration; treat request and response details as subject to revision.

Authentication & API Tokens

The Platform API authenticates each request with an API key — an opaque, organization-scoped credential issued by your organization's developer dashboard. Every request includes the key in the X-Cirrus-Api-Key header; there is no OAuth flow, no user impersonation, and no per-user credentials.

The token header

The header name is fixed. HTTP header names are case-insensitive, so X-Cirrus-Api-Key, x-cirrus-api-key, and any other casing all work. The value is sent verbatim — there is no scheme prefix (no Bearer, no Token) and no base64 wrapping.

The token itself is 56 characters — a fixed ci_live_ prefix plus 48 URL-safe random characters — and should be treated like a password. The ci_live_ prefix is deliberately greppable so a leaked value is easy to find in code review, incident logs, and secret-scanning rules.

X-Cirrus-Api-Key: ci_live_<...>

Creating a token

API tokens are managed in the developer dashboard at developer.cirrusinsight.com. Only organization admins can create or revoke tokens.

1. Sign in to the dashboard and navigate to API Tokens under the Developer section.

2. Click Create token.

3. Provide:

   • Label — a short human-readable name (e.g., production-booking-agent).
   • Scopes — one or more from the scope catalog below.
   • Expiration — Never, or a preset (30 days, 90 days, 1 year) or custom date.

4. Click Create. The token is displayed once:

   Copy and store the token in your secrets manager. If you lose it, you must revoke the token and create a new one.

────────────────────────────────────────────────────
⚠ Save this token now — it will not be shown again.
────────────────────────────────────────────────────

Scopes

A token grants access only to the scopes you explicitly select. Each public endpoint declares the scope it requires.

Scheduling

Scope	Grants access to
smart-scheduling:read	Read Smart Schedule definitions, fetch availability, list scheduled meetings
smart-scheduling:write	Book, reschedule, and cancel meetings

Webhooks

Scope	Grants access to
webhooks:read	List scheduled meetings, list webhook subscriptions, view delivery history
webhooks:write	Create and delete webhook subscriptions

Meeting content

Scope	Grants access to
transcripts:read	Fetch meeting transcripts (full text or by time-range window), chat messages, and Recording-bot lifecycle status

Cortex data — accounts, contacts, deals

Scope	Grants access to
accounts:read	Read account records, list contacts / deals on an account, fetch account activity
contacts:read	Read contact records, list contacts globally or by account, fetch contact activity
deals:read	Read deal records, look up deals by CRM source id (Salesforce etc.), list meetings linked to a deal
deals:write	Create deals; partial-merge updates to deals

Cortex insights — 8Ps and Q&As

Scope	Grants access to
insights:read	Read 8P deal-insight records (Profile / Problem / Pain / Power / Position / Phases / Process / Plan)
insights:write	Append insight items to 8P records — the "add insight" action
qna:read	Read the Discovery / RFI Q&A backlog on a deal (bundle or filtered by meeting)
qna:write	Create Q&A items, attach answers (auto-transitions to Answered on high confidence), transition state

Engagement — email blasts, buyer signals

Scope	Grants access to
email-blasts:read	Read email-blast campaigns, summary tiles, top-blast rankings, per-blast performance and activity timeseries, and per-recipient engagement rows
buyer-signals:read	Read tracked engagement (opens / clicks / replies) across every sent email — aggregate stats, daily activity, per-sent-email table, and per-recipient signal drill-downs (which is where reply-tracking data surfaces)

Identity — users and organizations

Scope	Grants access to
users:read	List and fetch users in the caller's org, read role assignments
users:write	Invite users, update role / activation / profile fields
organizations:read	Read the caller's org, read entitlements
organizations:write	Update org name, industry, primary email domain

Partner delegation

Scope	Grants access to
partner:act-as-child	Act on child organizations via the X-Cirrus-Acting-On header. Only issuable to tokens from partner-admin orgs. See Partner Delegation.

A token can hold any subset of scopes. Some endpoints require two scopes — reading contacts by account requires both contacts:read and accounts:read, because seeing contacts on a specific account implies visibility of the account. The response body on a 403 insufficient-scope names the missing scope.

For a read-only reporting bot, *:read scopes are enough. An end-to-end booking + Cortex-sync agent needs the relevant :write scopes too. Grant the minimum each integration actually needs; the platform enforces least privilege on every request.

If a request hits an endpoint requiring a scope your token doesn't carry, the response is 403 Forbidden with a problem-details body naming the missing scope:

{
  "type": "https://docs.cirrusinsight.com/platform-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This token does not include the required scope 'smart-scheduling:write'.",
  "requiredScope": "smart-scheduling:write"
}

Acting on child organizations

If your organization is a partner-admin (Cirrus reseller, MSP, systems integrator, or enterprise HQ with subsidiary orgs), your token can act on any of your child organizations by carrying an extra header:

One token, N children, per-request selection. The header requires the partner:act-as-child scope and only applies to child organizations Cirrus has linked to your partnership.

For the full contract — how children are enumerated, how scope intersection works, error semantics, and per-child rate-limit attribution — see Partner Delegation.

X-Cirrus-Api-Key: ci_live_<...>
X-Cirrus-Acting-On: org_<childId>

Expiration

Tokens with an expiration date stop working at midnight UTC on that date. The first request after expiry returns 401 Unauthorized:

Tokens created with Never expire have no automatic expiration; they remain valid until explicitly revoked.

You can change a token's expiration after creation by editing the token in the dashboard. Editing does not change the token value.

{
  "type": "https://docs.cirrusinsight.com/platform-api/errors/subscription-expired",
  "title": "API token expired",
  "status": 401,
  "detail": "This API token expired at 2026-09-01T00:00:00Z. Issue a new token from the developer dashboard.",
  "expiredAt": "2026-09-01T00:00:00Z"
}

Revocation

Revoke a token at any time from the dashboard. Revoked tokens stop working within 60 seconds — subsequent requests return 401 Unauthorized.

If a token may have been exposed (committed to a repo, posted in a Slack message, etc.), revoke it immediately and issue a new one. Do not attempt to rotate the token value in place — there is no rotation endpoint; the model is revoke + reissue.

Listing and editing tokens

The dashboard lists every active and revoked token for your org with:

• Label — what you named it
• Scopes — what it can do
• Last used — most recent request timestamp
• Calls (last 24h) — usage volume
• Expires — when (or Never)
• Status — Active / Expired / Revoked

Use this for routine hygiene: revoke unused tokens, narrow scopes on tokens that don't need write access, set explicit expiration on tokens previously created as Never.

Token security checklist

• Store tokens in a secrets manager — never in source control or shared chat tools
• Use separate tokens per service / environment (e.g., one for production, one for staging, one for your CI pipeline)
• Set an explicit expiration; rotate at least annually
• Grant the minimum scopes each token actually needs
• Revoke tokens belonging to departed team members or decommissioned services
• Do not embed tokens in client-side code, browser-visible JavaScript, or mobile apps — the Platform API is server-to-server only
• Do not share a single token across multiple unrelated services — usage attribution becomes impossible

What's next

• Platform API Overview
• Errors reference
• Smart Schedules endpoints