Scoped API tokens

An API token is a credential that stands in for you when something other than a browser needs to talk to Synacl — a script, a scheduled job, a tool on your laptop, or an AI agent. It authenticates as your account, but only for the scopes you tick when you create it.

Tokens live under Settings → API & Agents.

Availability. API & Agents is enabled per account. If you don't see it under Settings, it isn't switched on for you yet.

Scopes are capabilities, not roles

A scope is one of the same permissions that team roles are built from — device:view, dashboard:edit, and so on. Ticking device:view means "this token may read devices and their telemetry", and nothing more. There is no "read everything" or "admin" scope; you pick the individual capabilities.

Two rules bound every token:

1. A token can never exceed what your own account can do. If you are a team member with a Viewer role, a token you create is read-only no matter what you tick — Synacl refuses to mint a token carrying a permission you don't hold, and tells you which ones it rejected. Scopes are a way to hand out less than your access, never more.
2. Only a fixed list of scopes can go on a token at all. Some capabilities that exist for people are deliberately not available to tokens (below).

A token tracks your access as it changes

That first rule isn't only checked when the token is created. Every request a token makes is checked against what its creator can do right now — not against what they could do on the day it was minted. If that person's role is narrowed, or a role is taken away from them, their tokens lose the same permissions at the same moment. A token does not keep the access it was born with.

So a token can only ever shrink. It can never do something its creator cannot do, even if it was minted with a broader list of scopes than they now hold. If you are tightening someone's access, you do not have to hunt down their tokens first to make the change take effect — though you should still delete them, so nothing is left holding a credential it can't use.

What you can grant

That is the complete list. It covers building things out — registering a gateway, adding devices and their tags, assembling a dashboard, writing alert rules — and reading what already exists.

What you cannot grant

These are refused even if your own account has them:

• Anything that deletes. No device:delete, gateway:delete, dashboard:delete, rule:delete, or any other delete. Deletions are the hardest thing to undo, so they stay in the app where a person confirms them.
• Device commands (device:command). Switching a relay, driving a valve or moving an actuator has a physical consequence and is not something a token can do. Keep control in the app, in a rule, or in a macro.
• Billing. No plan changes, no payment settings.
• Team and role management. A token cannot invite anyone, change anyone's role, or edit custom roles.
• Wildcards. There is no * or device:*; every scope is listed explicitly.

If a tool asks for one of these, the request is rejected and the rejected scopes are named. That is expected, not a fault on your side — it means the tool asked for more than tokens are allowed to carry.

Create a token

1. Go to Settings → API & Agents and create a new token.
2. Give it a label that names what will use it — "nightly export script", "commissioning laptop". This is how you will identify it later when deciding what to revoke.
3. Tick the scopes it needs, and nothing else.
4. Create it.

The token is shown exactly once. Copy it before you leave the screen. It is never displayed again — not to you, and not to support. If you lose it, delete that token and create a new one.

Paste it straight into wherever it belongs — a password manager, your tool's secret store, a CI secret. Don't park it in a text file "for a minute".

Manage and revoke

The API & Agents list shows each token's label, its scopes, when it was created, when it was last used, and when it expires. Tokens issued to an app you approved over MCP appear here too, named after the app that holds them; the connected-apps list is the easier place to cut one of those off, because disconnecting an app revokes every token it holds at once.

• Delete a token to revoke it. Anything still using it starts getting rejected within seconds — you don't have to wait for the token to expire. Do this the moment you suspect a token has leaked, and when a tool or a laptop is retired.
• Scopes can't be edited after creation, and the value can't be re-read. To change what a token can do, create a replacement, move the tool over to it, then delete the old one.
• Once past its expiry, a token stops working. Create a new one.
• "Last used" is worth reading. A token that has never been used is one you can delete. A token being used at a time nothing should be running is worth investigating.

Handling tokens safely

• One token per tool. Sharing a single token across three scripts means revoking it breaks all three, and "last used" tells you nothing about which one is misbehaving.
• Grant the narrowest set that works. If a script only reads, give it view scopes. Adding write scopes "in case" costs nothing until it costs something.
• Never commit a token to a repository, paste it into a support ticket or a chat, or leave it visible in a screenshot. Treat it exactly like your password — it authenticates as you.
• A token is not covered by your second factor. Passkeys and two-factor authentication protect interactive sign-in; a token is a bearer credential and whoever holds it can use it. That is the whole point of keeping its scopes small.
• Rotate on staff change. A departing colleague's tokens lose their permissions as soon as their access is removed, but delete the tokens as well rather than leaving inert credentials in circulation.

See also: Connecting an AI agent · Team members and roles · Custom roles and permissions