Scoped API tokens

Updated 29 Sep 2026

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, authoring macros — and reading what already exists.

macro:run is different from every other scope

It is the only one that can move physical equipment: it lets the token start a macro. Everything else on the list changes records in Synacl; this changes something in the room.

Three things follow, and all are deliberate:

• Writing a macro is not running one. macro:create and macro:edit let a tool author and correct a sequence. The macro sits there, compiled and inert. Nothing moves until something runs it.
• It is never ticked for you. "Select all" skips it, and an app asking for it over MCP gets it presented unchecked on the approval screen. You can grant it — that is the point of it being on the list — but only by ticking it yourself.
• It is not sufficient on its own. The macro must also be marked "Let an AI agent run this" in the macro editor, per macro, by a person. A token holding macro:run is refused on every macro nobody has reviewed. Neither key works without the other, and software can only ever hold one of them.

Note the shape of that: a scope answers "may this credential act". It cannot answer "is this particular action safe". Nothing in Synacl is safety-rated, and no permission here substitutes for a hardwired emergency stop — see Macros.

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.
• Raw device commands (device:command). Writing a value straight to a coil, register or pin is not something a token can do, in any scope. Control goes through something reviewable: the app, a rule, or a macro you wrote and can read back — which is why macro:run exists and device:command does not.
• 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.

On a team, anyone with Manage members also sees every token and connected app held by any member of the workspace under Team → Agent access, and can revoke any of them — the place to go when a colleague's laptop is lost or an assistant they connected is misbehaving. Removing a member from the team revokes their tokens and connected apps in the workspace automatically.

• 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.

Seeing what a token has been doing

Each token also shows how many calls it made this month and how much data it sent back, and a View activity link opens its recent history.

The activity list shows changes, refusals and errors — not reads. If an agent creates a device, is refused a permission it doesn't hold, or hits an error, it appears there. Successful read calls are counted in the totals but not listed individually: a busy agent can make tens of thousands of them a day, and a list of "read your device list" repeated forty thousand times would bury the entries that actually matter.

So an empty activity list means this token changed nothing and was never refused — not that it did nothing. The call count above it is the number to read for that.

The numbers on the usage card

• Calls this month — every tool call, reads included.
• Data returned — the size of the responses sent back to the agent. This is the figure worth watching: everything Synacl returns goes into the agent's context, which is what you pay your AI provider for. A tool that answers with five hundred devices when you wanted five is visible here long before it shows up on a bill. Synacl cannot see your AI provider's own token usage — that happens on their side — so this is the closest honest measure of it.
• By agent — the split across your tokens and connected apps.

Whose totals you see depends on your role. If you can Manage members, the totals cover the whole workspace, including agents connected by other members; otherwise they cover your own tokens and apps only. The activity list under a specific token is only that token's.

You may see a row called "Before per-agent tracking" or "Other credentials on this account". That is real usage that isn't attributed to any token shown — traffic from before per-token counting started, a credential that has since been deleted, or a colleague's agent. It is listed rather than hidden so the per-agent rows always add up to the total.

One more thing that row can hold: before platform release 1.23.4, calls made with a personal token were counted there rather than against the token, so a token created earlier shows an empty activity list and no calls for that period — not because it was idle. From 1.23.4 on, every call a token makes is attributed to it. Connected apps were attributed correctly throughout.

There are currently no limits on agent API usage. The counters exist so that any future limit can be set from what real accounts actually do, rather than guessed at.

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.
• Staff changes are handled for you. Removing a colleague from the team revokes the tokens and connected apps they held in the workspace; narrowing their role trims their tokens to match. For anything else — a retired laptop, a script that no longer runs — delete the token yourself.

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