API tokens

Personal access tokens (they look like sencai_pat_...) let you - or a tool acting on your behalf, such as an AI agent - call Sencai’s API without using your interactive browser session.

A token reaches a specific, self-scoped set of endpoints: your own organization’s info, cloud instances, fleet agents, and compliance score for reading, plus a small set of gated write actions (creating an instance from an approved marketplace app, inviting a member, and triggering a runbook). It does not currently grant access to every resource in the Platform API - see AI agents (MCP) for the exact tool surface this powers.

Creating a token

1. In the app, go to Settings → Integrations → AI Agents (/gravity/settings/integrations/ai-agents).
2. In the API keys card, use the button that generates a new key.
3. Give the token a name so you can recognize it later - optional, but useful once you have more than one (for example, “Claude Desktop - laptop”).
4. Choose a scope: read for querying data only, or read/write if the token also needs to perform actions (see below). Read works on every plan; read/write additionally needs your organization’s AI-agent write access turned on and a paid plan before any write actually succeeds.
5. Optionally set an expiry date. Without one, the token stays valid until you revoke it.
6. Click Generate. Copy the token immediately - it’s shown only once, in a reveal dialog, and cannot be retrieved again after you leave the page. If you lose it, revoke it and create a new one.

Creating a token - even a read-only one - requires the Owner or Admin role in the organization.

Free-plan organizations can’t create tokens

Issuing an API token of any scope requires your organization to be on a paid plan (Starter and above). On the Free plan, generating a token fails with a payment-required error even though the button is always visible - upgrade the organization’s plan first. See Billing & Plans.

What a token can do

Read-scoped tokens can query your organization’s own data - organization info, cloud instances, fleet agents, and compliance score. Read/write-scoped tokens can additionally take a small set of actions on your organization’s behalf - but write actions are off by default: an organization Owner or Admin has to explicitly turn on AI-agent write access (the same AI-agent write access toggle) before a read/write token can actually perform a mutating action, on top of the token’s own scope, on top of the organization being on a paid plan. This is a deliberate, layered safeguard so a leaked or over-broadly-scoped token can’t act on its own - nothing happens with a write-scoped token until all three conditions are true.

This mechanism is what powers Sencai’s AI-agent integrations (tools that speak the Model Context Protocol, MCP - see AI agents (MCP)) as well as direct API access. Write actions are being rolled out gradually, so a specific write action may not be available yet even with write access turned on.

Listing and revoking tokens

The API keys card lists every token issued for the current organization - name, prefix, scope, and when it was last used. Only the prefix is ever shown again; the full value is never retrievable after creation, not even by Sencai staff.

Revoke a single token from its own row if it’s exposed or no longer needed - this is a soft revoke, so the token’s history stays in the audit trail, but the token itself stops authenticating immediately.

For an emergency - a key you believe is actively being misused right now - use the revoke-all control in its own card below the list. This invalidates every token belonging to the organization in one action, with a simple confirmation rather than a typed confirmation phrase, since speed matters more than ceremony in that moment. Both actions require the Owner or Admin role.

Revoking a token stops it working immediately: any integration or AI agent still holding it gets a 401 Unauthorized on its next call, with no grace period.

Storing a token

Treat a token exactly like a password:

• Don’t commit it to source control or paste it into a shared document.
• Prefer an environment variable or your platform’s secret manager over hardcoding it.
• Scope it to read unless you specifically need write access, and set an expiry when the integration’s lifetime is known in advance.
• If a token is ever exposed (a leaked log, a public repo, a shared screenshot), revoke it immediately and issue a new one.

Not yet the credential the official SDKs expect

The Go, Python, and TypeScript SDKs predate personal access tokens and are currently generated against a snapshot of the API that doesn’t include this token-scoped surface - call the endpoints directly (see the example on the Platform API overview) or use them via AI agents (MCP) until the SDKs catch up.

Troubleshooting

Status	Message	Meaning	Fix
402	API keys are available on paid plans (starter and above)...	Trying to create a token on a Free-plan organization	Upgrade the organization’s plan
401	Invalid API key	Unknown, malformed, or revoked token	Check you copied the full value; if it was revoked, generate a new one
401	API key has expired	Past its expiry date	Generate a new token
403	This API key does not have the read_write scope required...	Using a read-scoped token for a write action	Generate a new read_write-scoped token
403	AI-agent write access is not enabled for this organisation	Your organization’s write-access toggle is off	An Owner or Admin turns it on from the same AI Agents settings screen
403	AI-agent write actions require a paid account tier...	Organization is on the Free plan	Upgrade the organization’s plan

What’s next

• AI agents (MCP) - the read and write tools a token actually reaches, and how to connect an AI client
• Platform API overview
• Billing & Plans - token creation and write access are tier-gated
• FAQ