Authentication & scopes
The four scopes, how they combine, who a token belongs to, and how a caller resolves one.
Every call to the Meetily API, whether it comes from the meetily-pro CLI, an MCP client, or a script hitting the HTTP API directly, carries a bearer token. Each token is scoped to specific permissions and belongs to exactly one consumer.
Scopes
| Scope | Allows |
|---|---|
read | View meetings, transcripts, summaries, recording and job status, config, devices, models, and webhook subscriptions and delivery history. Also covers search. |
record | Start, stop, pause, and resume a recording. Implies read. |
write | Rename a meeting, edit speaker labels, set or regenerate a summary, control jobs (retry, pause, resume, cancel), and change several global settings. Implies read. |
delete | Remove meetings, recordings, and jobs the key created. Deleting the underlying audio/video files is a separate, opt-in permission. Never granted to a paired device, never an MCP tool. (Deleting a webhook you own is gated by read plus an owner check, not by delete.) |
No admin scope
There is no admin scope, and no admin HTTP route. Administration, meaning managing tokens, reviewing pairings, and revoking access, happens only in the desktop app, at Settings > Integrations. See Governance & administration.
How scopes combine
Scopes aren't independent switches you check one at a time. Three rules decide what a token can actually do:
writeimpliesread. A token withwritecan do everythingreadcan.recordimpliesread, the same way.deleteis independent in the permission algebra (it does not by itself implyread), but the Create key dialog always includesread, so in practice a key that can delete can also read. (Deleting a webhook you own is aread-scoped, owner-checked action, not adelete-scoped one.)
delete also carries two hard limits the other three scopes don't have: it's never granted to a paired device, and it's never exposed as an MCP tool. The only ways to invoke it are the CLI or a direct HTTP call using a token that holds it.
What you grant when you issue a token
read is always on - the Create key dialog marks it "Always on" and it cannot be turned off, so every issued token can see meetings and notifications. record, write, and delete are off by default - each one is something you turn on deliberately, not something a new token gets for free.
A new key is not live until you Allow it
Creating a key (or the built-in loopback key existing) is not enough, and neither is completing a device pairing. Under Apps & scripts, each key - and a newly paired device - starts "Not allowed yet" / turned off and connects only after you turn on its Allow toggle; until then calls with that credential return consumer_disabled. A key or device can be revoked from the same row.
write is broader than "edit the summary." Granting it lets a token change a meeting's title and speaker labels, regenerate a summary (which, on a hosted provider, spends that provider's credits), retry or otherwise control a job, and change several of the app's global settings. Treat write as "can change things," not "can edit text."
Who a token belongs to
Every token belongs to exactly one consumer, identified by a (kind, id) pair. Four kinds exist today:
first_party- the app itself, including the built-in CLI key.assistant- an MCP client, such as an AI assistant connected throughmeetily-pro mcp.app_key- a key you create yourself from Create key.device- a remote client that paired over the network.
A fifth kind, workflow, is reserved for the Workflows release and isn't available yet. See Workflows.
Connecting a new assistant grants read only by default. If it needs to control recording or write anything, grant that explicitly at install time (meetily-pro mcp install --write). See MCP server.
Revoking a token
Revoking a token is atomic and final. A revoked token is tombstoned, not merely deactivated - it does not come back on its own. Restarting the app, restarting a pairing, or downgrading out of Pro and back in does not re-mint or resurrect it. If you need access again after revoking, issue a new key or pair again.
Token expiry
| Consumer | Default expiry | Notes |
|---|---|---|
| App key | 90 days | Choose 90 days, 30 days, or Never at creation. Expiry is an absolute timestamp, not a rolling window - renewing is a manual action, there's no silent renewal. |
| Paired device | 90 days | Fixed from the moment the pairing is approved. |
| Built-in CLI key | Never | Exempt from the expiry that applies to other tokens. |
Resolving a token
A caller, whether that's the CLI, an MCP client, or a script hitting the HTTP API directly, resolves its token in this order:
- An explicit
--token-file <path>flag. - The
MEETILY_PRO_TOKENenvironment variable. - The loopback token file Meetily writes for the built-in CLI key.
There is no --token <value> flag. It's retired - the CLI no longer accepts it.
| Platform | Loopback token file |
|---|---|
| macOS | ~/Library/Application Support/pro.meetily.ai/gateway-token |
| Windows | %APPDATA%\pro.meetily.ai\gateway-token |
| Linux | $XDG_DATA_HOME/pro.meetily.ai/gateway-token |
That file only authenticates loopback requests, meaning a caller on this same machine. It doesn't help a caller reach the app over the network - network access needs a paired device token instead. See Pairing & remote access.
The built-in CLI key
Meetily ships a built-in key for the meetily-pro CLI. In the app it appears under Apps & scripts as the auto-created loopback key ("Meetily's own", Read); its reach is computer (loopback) and its consumer kind is first_party. It's inert by default: it grants nothing until you turn on its Allow toggle. It's also exempt from the 90-day expiry that applies to app keys and paired devices. See Enable & connect.
Related
Last updated on