Authentication
How Probably's MCP server and HTTP API authenticate: OAuth connections for AI apps and API keys for your own code, each scoped to one organization and optionally one Space.
Probably has two kinds of credential, and both are connections: an OAuth connection for an AI app a person signs in to, and an API key for your own code. Each acts as the member who made it, in one organization and optionally one Space, with the permissions they chose, and never past that member's role.
| OAuth connection | API key | |
|---|---|---|
| For | AI apps: Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex | Your servers, CI, cron jobs and automation tools |
| Made | By signing in and consenting, from the app | In Settings → Connections |
| Works on | The MCP server | The HTTP API and the MCP server |
| Sent as | An OAuth access token | Authorization: Bearer prb_... |
| Stops | When revoked, or when the member leaves | When revoked, or when the member leaves |
Permissions
A connection holds up to three permissions, and is offered only the tools they cover:
- Read: every connection reads what its scope reaches: Spaces, personas, products, library media, videos, events and credits.
- Make changes: free changes such as saving a product, approving a delivery, sharing a video or messaging Looky, and preparing paid work.
- Start paid work it prepares:
confirm_spend, which starts the work aprepare_or stage tool prepared. Without it, a prepared spend comes back with aconfirmUrlthe person opens to confirm it in the studio.
A tool a connection isn't offered reads as one that doesn't exist: a 404 over HTTP, an unknown tool over MCP.
A connection that makes changes can also be made with raw generation, off by default: its media
stages (generate_clip and voice) are made without critics or remakes and charged for their units
alone (see Pricing), unless a call passes raw: false. It's chosen when the key is made or the app is
connected, and stays as chosen: to change it, create a new key or connect the app again. Settings →
Connections marks the connections that have it, and get_connection answers raw.
Scope
A connection acts in one organization, the tenant boundary: it never reads or changes another's data. It may also be limited to one Space (a brand, creator or client), and then it reaches only that Space's videos, records, media and events, and can't create Spaces.
OAuth connections
An AI app that speaks MCP finds Probably's sign-in by itself (OAuth discovery and dynamic client registration). The person signs in with Probably's usual sign-in, then a consent page shows the app's name and where it will send them back, and asks for:
- the organization, when they belong to more than one;
- every Space, or one;
- whether the app may start paid work after they confirm it in the chat;
- whether its clips and recordings are made raw.
Access tokens last an hour, and clients refresh them without asking you; a refresh token is replaced on every use and lapses after 90 days unused. Every call reads the connection again, so revoking takes effect on the next call. See Connect an AI app for each app's steps.
API keys
Create the key
In the studio, open Settings → Connections and choose Create API key. Give it a name, optionally one Space, and what it may do: Make changes, Start paid work it prepares, and Raw generation.
Copy it once
The key starts with prb_ and is shown only once; Probably keeps only a hash of it. Store it as
a secret, such as an environment variable.
Send it
Send it as Authorization: Bearer prb_... to the HTTP API, or to the MCP server from a client
set up with a header.
A key that may start paid work must be limited to one Space that has a spend cap. Probably checks this when the key is made and again at every confirmation, so removing the cap stops the key spending. The Space's cap, shared with the studio, bounds what the key can spend.
To build and test without spending, create a sandbox key (prb_test_...) instead: it works with every tool in your organization's sandbox, answered from recordings and charged nothing. See Sandbox keys.
Keys are for servers. A request that carries an Origin header, as every browser request does, is refused with 403, so a key in a web page is useless to whoever finds it. Keep keys out of front-end code and out of repositories.
Revoking
Settings → Connections lists each member's connections and keys with their client, Space, permissions and last use; an admin sees every member's. Revoke one, and its next call is refused with 401. Removing a member from the organization stops all of theirs. To rotate a key, create a new one, switch your code to it, then revoke the old one.