---
title: Authentication and scopes
description: 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.
section: developers
order: 1
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/oauth/pure.ts, services/nodejs-cloud/lib/oauth/index.ts, services/nodejs-cloud/lib/mcp/workspace.ts, services/nodejs-cloud/lib/mcp/products.ts, services/nodejs-cloud/lib/mcp/limits.ts, services/nodejs-cloud/lib/auth/keys.ts, services/nodejs-cloud/app/.well-known]
features: []
---

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](/docs/developers/admin.md)) |

A key is shown once, when it is made. The cloud keeps only its hash and its first characters.

## API keys {#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 {#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](/docs/cloud/tasks-mcp.md).

### Naming agents on a shared key {#agent-header}

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](/docs/developers/conventions.md#limits)).

## OAuth for MCP clients {#oauth}

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 {#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](/docs/developers/globe) | `/workspace/mcp/globe` | `venom-globe` | 92 | `globe:read` `globe:write` |
| [Tasks](/docs/developers/tasks) | `/workspace/mcp/tasks` | `venom-tasks` | 221 | `tasks:read` `tasks:write` |
| [Flags](/docs/developers/flags) | `/workspace/mcp/flags` | `venom-flags` | 42 | `flags:read` `flags:write` |
| [Forms](/docs/developers/forms) | `/workspace/mcp/forms` | `venom-forms` | 19 | `forms:read` `forms:write` |
| [Incidents](/docs/developers/incidents) | `/workspace/mcp/incidents` | `venom-incidents` | 56 | `incidents:read` `incidents:write` `incidents:admin` |
| [Experiments](/docs/developers/experiments) | `/workspace/mcp/exp` | `venom-experiments` | 25 | `experiments:read` `experiments:write` |
| [People](/docs/developers/people) | `/workspace/mcp/people` | `venom-people` | 135 | `people:read` `people:write` |
| [Funnel](/docs/developers/funnel) | `/workspace/mcp/funnel` | `venom-funnel` | 38 | `funnel:read` `funnel:write` |
| [Support](/docs/developers/support) | `/workspace/mcp/support` | `venom-support` | 26 | `support:read` `support:write` |
| [Chat](/docs/developers/chat) | `/workspace/mcp/chat` | `venom-chat` | 32 | `chat:read` `chat:write` |
| [Status page](/docs/developers/status) | `/workspace/mcp/status` | `venom-status` | 16 | `status:read` `status:write` |
| [Comms](/docs/developers/comms) | `/workspace/mcp/comms` | `venom-comms` | 27 | `comms:read` `comms:write` |
| [Calendar](/docs/developers/calendar) | `/workspace/mcp/calendar` | `venom-calendar` | 41 | `calendar:read` `calendar:write` |
| [Admin](/docs/developers/admin) | `/workspace/mcp/admin` | `venom-admin` | 269 | `admin:read` `admin:write` |
| [Org](/docs/developers/org) | `/workspace/mcp/org` | `venom-org` | 10 | `org:read` `org:write` |
| [Computers](/docs/developers/computers) | `/workspace/mcp/computers` | `venom-computers` | 36 | `computers:read` `computers:write` |
| [Agents](/docs/developers/agents) | `/workspace/mcp/agents` | `venom-agents` | 48 | `agents:read` `agents:write` |
| [Studio](/docs/developers/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 {#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](/docs/developers/conventions.md).

## Related {#related}

- [API keys and key rotation](/docs/cloud/console-api-keys.md): creating, limiting, rotating and revoking keys.
- [Venom for agents](/docs/cloud/workspace-mcp.md#oauth): OAuth and scopes as the MCP server applies them.
- [Venom Cloud APIs overview](/docs/cloud/api-overview.md#credentials): every credential type, including the admin and daemon ones.
