Create a token and make your first API call

By the end of this tutorial you have made one successful authenticated call to the Sencai Platform API, you know how the API signals version changes, and the token you used no longer exists. It takes about 15 minutes.

The token is deliberately temporary. Creating a credential to try something once and then leaving it alive is how credentials leak, so revoking it is step 5, not an afterthought.

Before you start

• An organization on a paid plan (Starter or above). Token creation on the Free plan is refused, whatever scope you pick - see Organization plans. Step 1 checks this so you do not hit it at step 2.
• The Owner or Admin role in that organization. Creating and revoking tokens both require it - see Roles & permissions.
• A terminal with curl, or any HTTP client you prefer.
• A few minutes with the Platform API overview if you have not read it - the request and response conventions used below come from there.

1. Check your organization’s plan

Open Settings → Subscription (/gravity/settings/subscription) and look at which plan the organization is on. Any Owner or Admin can view and change it from this screen.

This matters more than it looks. Issuing an API token of any scope requires a paid plan. On the Free plan the Generate key button is still visible, but generating fails with a payment-required error (402) - so checking here first saves you a confusing dead end one step later.

Caution

If the organization is on the Free plan, you cannot finish this tutorial without upgrading it, and no amount of retrying or narrowing the scope will change that. See Organization plans for what each tier includes, and sencai.space/pricing for the numbers.

2. Create a read-scoped token

Go to Settings → Integrations → AI Agents (/gravity/settings/integrations/ai-agents). In the API keys card, click Generate key.

Give it a name you will recognize later, choose the read scope, and optionally set an expiry date as a second safety net. Read scope is all this tutorial needs: it queries data and changes nothing. Click Generate.

Copy the token immediately. It is shown once, in a reveal dialog, and cannot be retrieved after you leave the page - if you lose it, revoke it and create another. Keep it in an environment variable rather than a file:

export SENCAI_TOKEN="sencai_pat_..."

You should now see a row in the API keys list with the token’s name, prefix, scope, and when it was last used. Only the prefix is ever shown again. API tokens covers the full lifecycle, including expiry and the error each failure returns.

Note

Read/write tokens exist, but a write action needs three separate conditions to all be true - write scope on the token, AI-agent write access turned on for the organization, and a paid plan. This tutorial needs none of them. Stay on read.

3. Make one authenticated request

The base URL is https://api.sencai.space/api/v1. Ask the API which organization you are acting as:

curl https://api.sencai.space/api/v1/organisations/me \
  -H "Authorization: Bearer $SENCAI_TOKEN"

A successful response wraps its result in a data object (trimmed here):

{
  "data": {
    "id": 42,
    "documentId": "a1b2c3d4e5f6...",
    "name": "Acme Cloud",
    "account_tier": "professional"
  }
}

Two things worth noticing. You never passed an organization identifier: a token authenticates as you and is scoped automatically to the single organization it belongs to. And errors arrive as RFC 7807 problem documents, so a failure tells you its status and detail in the body as well as on the status line.

A 401 here means the token is missing, mistyped, or already revoked. A 403 means the token’s scope or your organization’s tier does not cover what you asked for. Both symptom tables - in API tokens and Troubleshooting - map each status to a fix.

Caution

The resource-family table on the Platform API overview is an orientation map, not a guarantee that every path on it is reachable with a token. Most of those paths need the signed-in browser session the web app itself uses. A personal access token reaches a narrower, self-scoped surface: your organization’s info, cloud instances, fleet agents, and compliance score for reading, plus a few gated write actions. Picking a path off that table and expecting your token to reach it is the most common way this step fails - AI agents (MCP) lists the surface exactly.

4. Read the version headers

Run the same call with -i so you see the status line and response headers, not just the body:

curl -i https://api.sencai.space/api/v1/organisations/me \
  -H "Authorization: Bearer $SENCAI_TOKEN"

The API is versioned by URL path, and /api/v1 is the only version today. That is why you should not expect a Deprecation, Sunset, or Link header in that output - their absence is the correct result for a current version, not a sign that something went wrong.

Those three headers are what the platform is designed to send once a version is marked deprecated, following RFC 8594: Deprecation carries the date it was deprecated, Sunset the date calls to it stop working, and Link points at a migration guide. After a sunset date passes, calls to that version are intended to be rejected with 410 Gone.

Two habits follow from that:

1. Write /api/v1 explicitly in your integration rather than relying on a default. It costs nothing today and is the entire preparation for a second version existing later.
2. Check Settings → API Versions (/gravity/settings/api-versions) when something changes. It lists each version with its Current badge, deprecation and sunset dates when set, the breaking-change list, and a migration guide link when one is provided.

Note

Sencai has not published a fixed notice window between deprecation and sunset, so treat the dates on the API Versions screen as the source of truth - see API versioning. The same records are readable at GET /api-version-policies, but that endpoint uses your signed-in session, not the token surface you just used.

5. Revoke the token

Return to Settings → Integrations → AI Agents, find your token’s row in the API keys card, and choose Revoke API key.

Confirm it worked by running the call from step 3 again: you should now get 401 Unauthorized. Revocation takes effect immediately with no grace period, so anything still holding the token fails on its next call.

This is a soft revoke. The token stops authenticating, but its history stays in your organization’s audit trail, so the record of what it did outlives the key itself. Revoking, like creating, needs the Owner or Admin role.

Tip

If you ever believe a key is being misused right now, use Revoke all keys in its own card below the list instead of hunting for one row. It invalidates every token belonging to the organization behind a single confirmation, because speed matters more than ceremony in that moment.

What’s next

• API tokens - scopes, expiry, storage, and the full error table behind every status you saw here
• AI agents (MCP) - the exact read and write tools a token reaches, and how to point an AI client at them
• API versioning - how deprecation and sunset are meant to work before you depend on them
• SDKs - the Go, Python, and TypeScript clients, and why they do not yet accept the token you just made
• Troubleshooting - the 401/403 symptom table, next to everything else that commonly goes wrong