Authentication & scopes
The four scopes, how they combine, who a token belongs to, and how a caller resolves one.
Authenticated calls to the Meetily API, whether from the meetily-pro CLI, an MCP client, or a script hitting HTTP directly, carry a bearer token. Each token is scoped to specific permissions and belongs to exactly one consumer.
Scopes
| Scope | Allows |
|---|---|
read | View full meeting content, including transcripts, summaries, search results, and exports, plus recording and job status, config, devices, models, and webhook subscriptions and delivery history. |
record | Start, stop, pause, and resume recording. Implies read; starting from another computer also requires the host to pre-arm remote recording. |
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 | Delete meetings. Removing their stored audio/video files is a separate opt-in. Available only to computer-reach credentials; never to paired devices or network-reach keys, and never as an MCP tool. |
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: it does not implyread. The Create key dialog always includesreadfor new keys. Deleting a webhook you own requiresreadand ownership, notdelete.
What you grant when you issue a token
read is always on in Create key and cannot be turned off. Because it exposes full meeting content, not just titles or notifications, grant it only to a client you trust with that content. record, write, and delete are off by default; each needs your deliberate choice.
A new key is not live until you Allow it
Creating a key is not enough. Under Apps & scripts, an app key or newly paired device starts "Not allowed yet" and connects only after you turn on its Allow control; until then calls return consumer_disabled. The built-in CLI uses the separate Allow the CLI on this computer strip. A key or device can be revoked from its 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.
Connecting a new assistant grants read only by default. Record, Write, and Delete are opt-in permissions in the AI Assistants (MCP) connection sheet. 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 | Never | Choose 30 days, 90 days, or Never at creation. Expiry is an absolute timestamp, not a rolling window - renewing is a manual action, with 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
The meetily-pro CLI and its MCP process resolve a 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.
The legacy --token <value> flag is recognized only to reject it with exit code 1. Direct HTTP callers manage their own Authorization: Bearer ... value; this resolution order does not apply to them.
| 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 |
The loopback file only authenticates requests from this computer and is never used implicitly for a non-loopback server. Network access needs an explicit network-reach credential: a paired-device token or an app key created with network reach. See Pairing & remote access.
The built-in CLI key
Meetily ships a built-in credential for the meetily-pro CLI. Its underlying name is loopback, its reach is computer, its consumer kind is first_party, and it has Read-only access. It is inert until you use Allow the CLI on this computer below the collapsed Apps & scripts header. It never expires. See Enable & connect.
Related
Last updated on