API tokens

API tokens have their own section, Settings → API Tokens, in the Personal group of the settings rail. Anyone can open it and see the tokens they hold; issuing a new token is admin or owner only.

This is the right place for any programmatic caller: scripts, integrations, CI jobs, MCP clients connecting from Claude Code.

What you'll see

• Claude and MCP connections: every Claude or MCP client connected as you in the last 30 days, with the client it reported (for example claude-code 2.1.240), the ProductOS tool-list version it loaded, when it was last used, and a status: Up to date, Reconnect (it has missed an announced update and is still in use), or Update available (smaller changes only). When one is behind, the section lists what reconnecting gets you and the steps for each client. The connector notification and the app-wide reconnect banner link here. See Keeping the connector up to date.
• Token list: name, display prefix, role, last-used timestamp, scopes, and a revoked marker. Tokens created by connecting claude.ai, Claude Desktop or Claude Code through OAuth carry a small oauth badge (tooltip: Connected app): their secret rotates automatically while the app stays connected, and revoking them here disconnects it.
• New token button: opens the issuance dialog

Issuing

• Name: what this token is for (e.g. "n8n production", "GitHub Actions for repo X")
• Role: the token's effective role. Defaults to commenter (read everywhere, no writes). Pick member for write-capable integrations. Tokens are capped at the issuer's role, an admin cannot issue an owner-level token.
• Scopes: read, write and admin chips (default read + write). They are recorded on the token, but what a token can do is decided by its role, not its scopes.
• Expiry: the dialog has no expiry field, so tokens issued here never expire automatically. (POST /api/v1/tokens accepts an expires_at if you mint tokens through the API.)

On save, the full token (pos_live_…) is shown exactly once. Copy it to your secret manager immediately, there's no recovery. The same dialog offers a ready-made claude mcp add … command under Use with Claude Code.

How capability works

There are no per-endpoint scope strings. Every API call runs as the role stored on the token at issuance, and each route checks that role against the same capability matrix a signed-in user gets.

If the issuer is later demoted, any token whose stored role exceeds their new role is revoked automatically, so you don't need to remember to revoke tokens when changing someone's role. Removing someone from the workspace revokes every token they issued in it.

Rotating / revoking

• Rotate: issue a new token with the same role; revoke the old once dependents are updated.
• Revoke: instant. In-flight calls return 401 immediately on the next request.

Common use

• Claude Code MCP: see MCP server. The "Send to Claude Code" dispatch flow issues a session-bound token automatically (member role, 24-hour expiry, named after the session); you only need to mint one manually if you're connecting Claude Code to ProductOS for general use.
• n8n / Make / Zapier: paste the token into the HTTP node's bearer auth.
• CI jobs: store in the secret manager; pass as Authorization: Bearer ….

Related

• Authentication guide
• Workspaces and roles: what each role can do via a token
• Errors reference