Skip to content
Sencai.docs

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.

A token can also read, read-only, the Admin Center handbook pages and contacts of its own organization. The handbook and the contacts are separate permissions, and which token gets which is explained in Letting an agent read your contacts. A token can never reach the password store.

Creating a token

Section titled “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). Both are available on every plan, including Free - but read/write needs your organization’s AI-agent write access already turned on before you can generate it: with the toggle off, creating a read/write token fails outright rather than succeeding as a token that can’t yet write. Turn the toggle on first (same screen, see below) if you need one.
  5. Optionally set an expiry date. Without one, the token stays valid until you revoke it - or until it stops qualifying on its own; see Listing and revoking tokens below.
  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, so a read/write token can only ever be issued by an Owner or Admin. This is enforced today. Being introduced: a per-token permission limit - a read/write token acting with at most an Admin’s permissions, and never more than the person who issued it currently has - is built but switched off by default. Until it’s on, what a token may do is decided by its scope, the AI-agent write access toggle, and its issuer still qualifying (see Listing and revoking tokens).

What a token can do

Section titled “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 even be created, let alone used to write. This is a deliberate, layered safeguard so a leaked or over-broadly-scoped token can’t act on its own. Turning the toggle off again after tokens already exist still blocks every one of them from writing, even though it doesn’t touch tokens that were already minted - so revoking write access for the organization doesn’t require revoking the tokens themselves. This doesn’t depend on a paid plan any more - a Free organization can turn the toggle on for its own read/write tokens the same as a paid one (see the note above); the toggle grants no exemption from the free configuration’s own resource limits.

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.

Letting an agent read your contacts

Section titled “Letting an agent read your contacts”

Contacts, the responsibilities matrix and the emergency sheet are personal data about third parties, so they are a separate permission from the handbook. To let an AI agent read them, issue the key with restricted permissions:

  1. On Settings → Integrations → AI Agents, start generating a key as above and choose the scope read.
  2. Switch on Restrict permissions. A list of permissions appears; it offers only permissions that you hold yourself and that may ever be given to a key. Passwords, the Admin Center’s write permissions, and billing or other critical permissions are never in it.
  3. Tick contacts:read for contacts, responsibilities and the emergency sheet, and handbook:read as well if the agent should read the handbook. Tick nothing else the agent does not need.
  4. Generate the key. In the list it carries an explicit chip naming the permissions it was given.

If you create keys through the API, send "mode": "explicit" together with a permissions list (for example ["handbook:read", "contacts:read"]). Sending permissions without that mode is refused, so a typo can never produce a key broader than you asked for.

What happens without that:

  • A read token created without restrictions is capped at Viewer permissions. That includes the handbook but not contacts, which start at Member. Where this per-token limit applies, a default read token gets 403 (“This API key’s own permission grant does not include contacts:read”) from the contact routes, and permission_denied from the contact tools in an MCP client. Treat a default read token as a handbook-and-operations reader, not a contacts reader.
  • A read/write token is capped at Admin permissions, which include contacts:read, so it reads contacts too. It needs AI-agent write access switched on to be created at all, and gives an agent more than reading requires, so a restricted read key is the better choice for an agent that only reads.

Either way, a key reads only what the person who issued it may still read. If that person is denied contacts:read, is demoted below Admin or leaves, the key stops reading contacts. The handbook tools need handbook:read and the contact tools need contacts:read; a key that has only one of them can read only that part.

Listing and revoking tokens

Section titled “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. The one exception is an MCP client asking only for the tool list or a ping: those two calls never touch your data, so they may still answer for up to about 15 seconds after revoking. Every tool that returns data is refused at once.

A token can also stop working without anyone revoking it, because it represents authority delegated by the person who created it:

  • If the token’s issuer is removed from the organization, or is demoted below Admin, the token itself is untouched (it isn’t revoked, and doesn’t show as revoked in the list) but every call it makes gets a 403 until someone with Admin or above creates a fresh one.
  • If the organization is suspended for non-payment, the token keeps working for reads. Among its write actions, creating an instance or inviting a member get the same 403 a suspended organization’s browser session gets; triggering a runbook doesn’t - that action isn’t blocked for a suspended organization from the browser either, so a token doesn’t lose anything the app itself would still let you do.
  • If the organization is deleted, the token gets a 403 for every call, read or write.

A token that predates this check and has no recorded issuer at all keeps working under its original scope regardless of who is or isn’t currently an Admin - there’s no “re-verify the issuer” to apply.

Storing a token

Section titled “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.

Troubleshooting

Section titled “Troubleshooting”
Status Message Meaning Fix
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 This API key's own permission grant does not include contacts:read in this organisation. (or another permission) The key was issued with restricted permissions that leave this out, or is a default read token, which is capped at Viewer permissions Issue a new key with Restrict permissions and the permission ticked, see Letting an agent read your contacts
403 This API key's issuer is no longer a member of this organisation... / ...no longer holds an administrator role... The person who created the token left the organization or was demoted below Admin Have a current Admin or Owner generate a new token
403 This organisation is suspended and read-only... The organization is suspended for non-payment (reads still work) Resolve the payment issue with billing support
403 This organisation no longer exists. The organization was deleted Not fixable - the token’s organization is gone
409 A quota/conflict error on the resource you tried to create The write would take the organization past the free configuration’s limit Move the organization to a paid plan, or free up room under the limit

What’s next

Section titled “What’s next”