Tokens and scopes

A personal API token lets your own tools and agents work with Lobbe for you.

Developer mode

Tokens need Developer mode: in the app, open Account and find it in the Developers section. It is off for a new account. Turn it on and Connections appears, where you make and manage tokens.

Turning developer mode off pauses every token of your account: each request answers 403 DEVELOPER_MODE_OFF, and no token is revoked. Turn it back on and the same tokens work again.

How a token works

• A token belongs to one person, the account’s owner, and acts for that account: what it sends spends that account’s minutes, and what it reads is that account’s.
• Every request sends it in the Authorization header: Authorization: Bearer $LOBBE_TOKEN.
• The app shows a token once, when you make it. Lobbe keeps only a hash of it, so a lost token can’t be shown again: make a new one.
• You can have up to 10 active tokens at a time. Revoked and expired tokens don’t count.
• A token expires after 30, 90 or 365 days, or never (Never). You choose when you make it.
• A token’s scopes are fixed when you make it. If a tool needs more or less, make a new token and revoke the old one.
• To revoke a token, open it in Connections and tap Revoke twice. It stops working at once, and anything it already sent stays in your archive.

The scopes

Each scope opens one kind of access. The create form shows the eight in three groups:

• Meetings: recordings:read, recordings:write, recordings:query
• Series: series:read, series:write, series:query
• Account: account:read, account:write

Scope	In the form	What it does	Routes	Spends minutes	Rollout switch
recordings:read	Read	Lists your finished meetings and reads their transcript, Lobbe and status.	GET /recordings/ready, GET /recordings/{id}/bundle, GET /recordings/{id}/status, GET /events	No	None
recordings:write	Send meetings	Sends audio to make a Lobbe; can skip naming or retry a failed meeting.	GET /recordings/{id}/status, GET /events, POST /recordings, POST /recordings/{id}/naming, POST /recordings/{id}/retry	Yes	API_WRITE_ENABLED
recordings:query	Search and ask	Searches your meetings and asks them questions.	GET /recordings/search, GET /recordings/{id}/ask/quote, POST /recordings/{id}/ask	Yes	API_QUERY_ENABLED
series:read	Read	Lists your series and reads their settings and vocabulary.	GET /series/readable, GET /series/{id}, GET /series/{id}/keyterms	No	None
series:write	Create and edit	Creates a series and changes its name, settings and vocabulary.	POST /series, PATCH /series/{id}, PUT /series/{id}/keyterms	No	API_WRITE_ENABLED
series:query	Ask a series	Asks a question of every finished meeting in a series.	GET /series/{id}/ask/quote, POST /series/{id}/ask	Yes	API_QUERY_ENABLED
account:read	See balance and settings	Reads your balance, settings, vocabulary and memory.	GET /account, GET /account/keyterms, GET /account/memory	No	None
account:write	Change settings	Changes your settings and vocabulary, and edits or deletes memory notes.	PATCH /account/settings, PUT /account/keyterms, PATCH /account/memory/{id}, DELETE /account/memory/{id}	No	API_WRITE_ENABLED

• Only recordings:read (Meetings, Read) is ticked by default. No scope is required, but a token needs at least one.
• GET /whoami answers every token, whatever its scopes.
• Scopes don’t include one another. A token that can send meetings but not read them (recordings:write without recordings:read) reaches only the meetings it sent itself, and of those only their status and their events: never their transcript, never their Lobbe, and never another meeting.
• recordings:query without recordings:read has no list of meetings and no bundle, but search finds any of your finished meetings by its words, and the token can then ask that meeting.

The daily cap

A token that can spend minutes can have a daily cap: the most minutes it may spend in any 24 hours.

• It is optional, and the default is Unlimited. The form shows Daily spending cap only when you tick a scope that spends.
• A day here is any 24 hours in a row: each request is checked against what the token spent in the 24 hours just before it.
• It counts this token’s own spending only: each meeting it sends, from the moment Lobbe accepts it, and the price of each Ask. A meeting you delete later still counts.
• A request that would go over answers 429 TOKEN_DAILY_CAP: see Minutes, caps and limits.
• Change it on the token’s page in Connections, under Daily cap: a whole number of minutes, from 1 to 100,000.

Caution

A token with no cap, in someone else’s hands, can spend every minute of your balance.

What no token can do

No scope gives a token these. They stay with you, in the app:

• deleting a meeting or a series;
• showing anything to another person: share links, series invites and members, a series’ email list, sending a summary by email;
• buying minutes, and payments;
• changing your name, phone number, email, password or sign-in sessions, or the Delete audio after the Lobbe setting;
• making or revoking tokens, and turning developer mode on or off;
• moving a meeting you already sent into a series (a token can file a meeting in a series when it sends it).

Rollout

Note

Sending meetings, creating and editing series, changing settings, search and Ask through a token are being switched on gradually. If the form in Connections doesn’t offer a scope, it isn’t available to your account yet.

Keep it safe

• Never put a token in a URL: addresses end up in logs and in browser history.
• Never commit a token to a repository. Read it from an environment variable or a secret store.
• Never paste a token into a chat, an issue tracker or an email, a chat with an AI assistant included.
• Give each tool its own token, with the fewest scopes it needs and, if it spends, a daily cap. Then you can revoke one without stopping the others.
• If a token leaks, revoke it in Connections at once.