Signing In & Credentials

The plugins use two credential types: a binding credential for a repo and an MCP access token for a person. Each plugin's page has its own setup walkthrough.

Expand

Two credentials, two jobs

The two aren't interchangeable: a binding credential belongs to a repo, and an MCP access token belongs to a person.

A binding credential is per machine. Every /login and every Generate new secret issues a credential scoped to one binding. When you revoke one machine's credential, the others keep working. A new /login from the same machine replaces its old credential instead of adding another. The plugin adds .provenmap/ to .gitignore; leave it there.

An MCP access token acts as the person who generated it. Its writes go into the token's own working copy, apart from that person's edits in the portal, and what it writes is recorded under that person's name. Each person should generate their own token.

For workspace-wide work, connect at the root board. For work on one system, connect a repo to an app board. Root boards never bind repos.

Getting one

You can get either credential through browser sign-in or from the portal.

Browser sign-in — /login

Every plugin's /login runs an OAuth 2.0 device authorization grant (RFC 8628). You sign in and approve access, and the plugin receives and stores the credential.

The secret never appears in the conversation.

The browser does not have to be on the same machine. If the plugin can't open one, it prints a URL and a user code. The plugin's own environment still needs API access for /login to finish.

To approve an MCP access token, you need workspace admin, the same permission that generating one in the portal needs. If you aren't an admin, ask one to generate a key and take the portal path instead. Approving a binding credential doesn't need workspace admin; you pick from boards that already have a binding.

Note

Sign-in starts from the plugin, not your MCP client. If you add …/api/mcp as a generic HTTP server, no authorization prompt arrives. Run /login instead.

A key from the portal

Take this manual path for hand-managed credentials, CI and self-hosted instances, or when you don't have permission to approve browser sign-in.

• MCP access token — Use a key → Generate token, on the Workspace agent access sheet (changed 12 October 2026). An app board hub's App agent access doesn't generate tokens. MCP Access covers scopes in full.
• Binding credential — for a reference Code Plugin binding, Generate new secret under Binding actions → Copy credentials. An app's governing binding has no dialog: its credential comes from /login. Connecting Sources covers that setup.

Both dialogs show the secret exactly once, with setup snippets. We store only a hash, so we can't show it again.

Delivering it

The binding credential: local file or CI environment

The binding credential lives in .provenmap/credentials.json: exactly two fields, in a file only the owner can read and write. The board and branch it authorizes are settings in .provenmap/config.json beside it. The plugin ignores a credential field left in config.json, and /status says so.

/login writes both files, and /configure validates values you enter by hand. For CI, use PMAP_BINDING_TOKEN, PMAP_API_SECRET, PMAP_BOARD_SLUG, PMAP_BRANCH, and PMAP_BASE_URL. Environment values override the files.

The code plugin never reads MCP tokens, updates host MCP config, or uses connector URLs.

The MCP access token: pick one of three

The workspace plugin reads its token from the first place it finds one:

Add PMAP_MCP_URL alongside the token for a self-hosted endpoint.

Important

On Codex, /login gets you the token but cannot finish setup. It prints one manual step, PMAP_MCP_TOKEN; set it, then start a new Codex thread. Only Claude Code writes the host MCP entry for you.

Keeping secrets out of the conversation

The plugins keep every credential out of what the model reads. You put a credential in its file or the environment, and the plugin's scripts read it from there. When a command needs to know what is set, it gets each field's state, never the value.

/configure checks the binding credential without opening the file. It reports bindingToken and apiSecret each as present, missing or malformed, and shows only the secret's prefix, such as pmap_cp_live_****.

On Claude Code 2.1.287 or later, the code plugin and the workspace plugin also enforce this on every tool call:

• Credential files are off limits. The model can't read, search or print .provenmap/credentials.json, the sign-in state /login keeps, ~/.provenmap/architect-mcp.json, PMAP_API_SECRET or PMAP_BINDING_TOKEN. A blocked call names the command to run instead, such as /configure to check a credential or /login to replace it.
• Secrets elsewhere arrive masked. A ProvenMap secret in a tool's output reaches the model as its prefix and ****. That covers one left in config.json or a host MCP config.

Codex and Cursor have no equivalent. Their commands follow the same rule, but nothing stops a request you type yourself.

Why the connector URL includes its key

A claude.ai custom connector calls our server from Anthropic's infrastructure. A connector has nowhere to put a header, so the key goes in the URL:

https://platform.provenmap.com/api/mcp/k/pmap_mcp_live_...

Warning

That URL is the secret. Anyone who has it gets everything the token grants. Treat it as you would the token: don't paste it into a ticket, chat, or repo.

The keyed URL covers MCP tool calls only. CLI commands such as /sync, /status, and /login still need egress from the environment where they run.

Which path your environment allows

Outside desktop, browser, environment or network limits can require the portal path.

Tip

Start an integration with a read token. Expand access after you verify what the agent does with it.

Revoking, rotating, expiring

An MCP access token stops working as soon as you revoke it in Workspace agent access, and the next call made with it gets a 401. That list holds every token for the workspace, tokens from /login included, so you revoke any token in one place.

Signing out of the workspace plugin (/logout) only removes the copy on that machine; the token stays valid until you revoke it. Every token also has an expiry, so an abandoned token eventually stops working.

A binding credential is revoked one machine at a time. Revoke the machine's row under Plugin connections on the Workspace agent access sheet. A reference Code Plugin binding also lists its machines under Connections, in the dialog that Binding actions → Copy credentials opens on the Bindings card. Both places show whether each credential is never used, active, stale, or revoked.

The code plugin's /logout also revokes that machine's credential on the server. Binding credentials don't expire, so revoking one is the only way to end it by hand. A credential shows never used when it was issued but never connected, usually because setup didn't finish on that machine.

Every credential dies with its creator's membership. Suspend the member who created a binding credential or an MCP access token, or let them leave, and its next call is refused. The message says so. That covers a CI credential too. Mint CI credentials from an account that stays in the organization, and when its owner leaves, sign in again to mint a new one.

What's next