Authentication and scopes
Which credential to use for each Venom API. Personal and team API keys, OAuth 2.1 for MCP clients with its endpoints and token lifetimes, the scopes per product, service agents, and the keys that belong to app runtimes.
Every request carries one credential as Authorization: Bearer <credential>. The workspace APIs never read a cookie.
| Credential | Looks like | Use it for | Made by |
|---|---|---|---|
| Personal API key | vck_… with "This key is mine" on |
scripts and agents that act as you, on MCP and REST | you, in Settings, API keys |
| Team API key | vck_… |
shared services, CI, the venom CLI on /v1 |
a developer or admin, in Settings, API keys |
| OAuth access token | vga_… |
MCP clients that sign in through a browser (Claude Code, ChatGPT, Cursor) | the OAuth flow below |
| SDK key and client id | vfs_…, vfm_…, vfc_… |
your app's runtime calls to Flags, Experiments and Incidents | each Flags environment |
| Admin key and admin token | vak_…, the deployment's admin token |
the admin API under /api/admin/v1 |
the operator (Build on Admin and the mesh) |
A key is shown once, when it is made. The cloud keeps only its hash and its first characters.
API keys
A personal key belongs to a member. On the workspace APIs it acts as that member: their role is the ceiling, and writes are audited as that member through the agent. Use one for anything that should do what you could do in the app.
A team key has no member. What it may do depends on the product, because some products are personal:
| Product | A team key |
|---|---|
| People, Calendar, Admin | is refused: they need a member |
| Status page | reads only |
| Org and teams | reads teams that are not private; with a bound service agent, acts as that agent |
| Tasks | reads; with a bound service agent, acts as that agent in the teams the admin picked |
| Notes | reads the shared vaults; it cannot write notes and never sees a personal vault |
| Support | works: the inbox is the org's |
| Chat | acts as an agent member |
| Flags, Experiments | reads and writes flags as the key (flags:read and flags:write) |
| Comms | acts as an agent: reads, and sends only as the sending profile allows agents |
Each product page has the exact rule under "Authentication and scopes".
Service agents
An admin can bind a team key to a named service agent (Venom Tasks, Settings, Members and agents, Agent access).
The agent then shows by name on everything it does, and the admin can narrow it: read only, which apps (Notes,
Tasks), and which teams. The scope holds on /workspace/mcp, /api/v1 and the per-app servers. Agents that act for
a member (a personal key, a connected app) follow the member's role instead. See
Venom Tasks for agents.
Naming agents on a shared key
Rate limits are per agent. Several daemons or sessions that share one key each get their own window when they send
x-venom-agent: <name>. The key keeps a ceiling over all of them (see limits).
OAuth for MCP clients
Clients that connect by URL run OAuth 2.1 against the cloud's one authorization server. You don't need to build any of this to use a client such as Claude Code; it is here for people writing their own client.
| What | Where |
|---|---|
| Protected resource metadata (RFC 9728) | /.well-known/oauth-protected-resource/workspace/mcp, and …/workspace/mcp/<product> for a product endpoint |
| Authorization server metadata (RFC 8414) | /.well-known/oauth-authorization-server |
| Dynamic client registration (RFC 7591) | POST /globe/oauth/register |
| Authorization | /globe/oauth/authorize (a browser page: the member signs in and ticks the scopes) |
| Token and refresh | POST /globe/oauth/token |
| Revocation | POST /globe/oauth/revoke |
- PKCE with
S256is required. Redirect URIs are checked against the registration (at most 10). - The resource is the MCP endpoint,
https://<cloud>/workspace/mcp. A product endpoint such as/workspace/mcp/tasksis the same resource narrowed to one product, so one grant works on every endpoint it has scopes for, and on the REST twin under/api/v1. - Lifetimes: an authorization code 60 seconds, an access token (
vga_) 1 hour, a refresh token (vgr_) 30 days. - A
401from an MCP endpoint carriesWWW-Authenticatepointing at the protected resource metadata, which is how clients discover all of the above. - A member sees and disconnects their connected apps in the console (Connect an agent,
/connect). Disconnecting stops the app's tokens at once.
Scopes
Each product has a <product>:read and a <product>:write scope. Incidents also has incidents:admin. A tool needs
its product's :write scope when it changes something and :read otherwise; the cross-product workspace_* tools
ask each product they touch. The scope only narrows: the member's role still decides.
| Endpoint the client connects to | Default grant when the client names no scope |
|---|---|
/workspace/mcp/<product> |
that product's :read and :write (never incidents:admin) |
/workspace/mcp |
:read and :write on every product except Admin; never incidents:admin |
A client that sends scope= gets at most what it asks for. On a product endpoint, scopes of other products are
dropped, and a request left with none is refused with invalid_scope. Admin scopes (admin:read, admin:write
on the combined endpoint, and incidents:admin anywhere) are granted only when the client asks for them. On the
consent screen read is always on; the member can untick write or admin. Funnel's tools also accept people:read
and people:write, from before Funnel had its own scopes.
A tool outside the grant is refused with words that name the missing scope and how to reconnect.
The scopes, generated from the product registry:
| Product | Endpoint | Server name | Tools | Scopes |
|---|---|---|---|---|
| Notes | /workspace/mcp/globe |
venom-globe |
92 | globe:read globe:write |
| Tasks | /workspace/mcp/tasks |
venom-tasks |
221 | tasks:read tasks:write |
| Flags | /workspace/mcp/flags |
venom-flags |
42 | flags:read flags:write |
| Forms | /workspace/mcp/forms |
venom-forms |
19 | forms:read forms:write |
| Incidents | /workspace/mcp/incidents |
venom-incidents |
56 | incidents:read incidents:write incidents:admin |
| Experiments | /workspace/mcp/exp |
venom-experiments |
25 | experiments:read experiments:write |
| People | /workspace/mcp/people |
venom-people |
135 | people:read people:write |
| Funnel | /workspace/mcp/funnel |
venom-funnel |
38 | funnel:read funnel:write |
| Support | /workspace/mcp/support |
venom-support |
26 | support:read support:write |
| Chat | /workspace/mcp/chat |
venom-chat |
32 | chat:read chat:write |
| Status page | /workspace/mcp/status |
venom-status |
16 | status:read status:write |
| Comms | /workspace/mcp/comms |
venom-comms |
27 | comms:read comms:write |
| Calendar | /workspace/mcp/calendar |
venom-calendar |
41 | calendar:read calendar:write |
| Admin | /workspace/mcp/admin |
venom-admin |
269 | admin:read admin:write |
| Org | /workspace/mcp/org |
venom-org |
10 | org:read org:write |
| Computers | /workspace/mcp/computers |
venom-computers |
36 | computers:read computers:write |
| Agents | /workspace/mcp/agents |
venom-agents |
48 | agents:read agents:write |
| Studio | /workspace/mcp/studio |
venom-studio |
30 | studio:read studio:write |
| Cross-product | /workspace/mcp |
venom |
16 listed (every tool callable by name) | every product's :read and :write |
1179 tools in all. Generated from the code on every docs build.
Errors
| Status | When |
|---|---|
401 |
no credential, an unknown, revoked or expired one, or an OAuth token issued for another resource |
403 |
the credential is valid but may not do this: a read-only role, a team key on a personal product, a missing add-on, a scope the grant lacks, another agent's claim |
The message says which. See Errors, limits, idempotency and pagination.
Related
- API keys and key rotation: creating, limiting, rotating and revoking keys.
- Venom for agents: OAuth and scopes as the MCP server applies them.
- Venom Cloud APIs overview: every credential type, including the admin and daemon ones.