Skip to content
Docs menu

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.

View .md

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 S256 is 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/tasks is 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 401 from an MCP endpoint carries WWW-Authenticate pointing 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.