Signing In & Credentials

There are two credential types: one for a repo, one for a person. This page is the reference for both. Each plugin page includes its setup walkthrough.

Getting a credential and delivering it are separate steps: get it in the browser or portal, then put it where the plugin, client, or connector can read it.

Two credentials, two jobs

They look similar but are not interchangeable: a binding credential belongs to a repo, and an MCP access token belongs to a person.

Before storing either credential:

A binding credential is per machine. Every /login and every Generate new secret action issues a credential scoped to one binding. Revoking one machine's credential leaves the others 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 join that person's working copy, so 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. These are workflow choices, not job-title permissions. Root boards never bind repos.

Getting one

Both credential types can be obtained through browser sign-in or the portal. Use the portal path for managed credentials, CI, self-hosted instances, or restricted environments.

Browser sign-in — /login

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

Nothing is copied by hand, and the secret never appears in the conversation.

The browser does not have to be on the same machine. If the plugin cannot open one, it prints a URL and user code. /login still requires API access from the plugin environment.

Approving an MCP access token requires workspace admin, the same permission required to generate one in the portal. If you are not an admin, ask one to generate a key and use the portal path instead. Approving a binding credential does not require workspace admin; you pick from boards that already have a binding.

Note

Sign-in starts from the plugin, not your MCP client. Adding …/api/mcp as a generic HTTP server and waiting for an authorization prompt will not work. Run /login instead.

A key from the portal

Use the manual path for hand-managed credentials, CI, self-hosted instances, and anyone without permission to approve browser sign-in.

• MCP access token — Generate a key, on the Architect access sheet of a command center. Restrict it to one app board there if you want to limit access. An app board hub's Agent access does not generate tokens. MCP Access covers scopes and restrictions in full.
• Binding credential — the dialog that opens when you bind a governing source, or Generate new secret in the binding's credentials dialog afterwards. Each generate issues a fresh credential; the ones already in use keep working until you revoke them. Connecting Sources covers that setup.

Both dialogs show the secret exactly once with setup snippets. We cannot show it again because only a hash is stored.

Delivering it

Store binding credentials in a local file or CI environment variables. For an MCP access token, choose one of the three destinations below.

The binding credential: local file or CI environment

A binding credential is stored in .provenmap/credentials.json, a file holding exactly two fields, readable and writable only by the owner. The board and branch it authorizes are settings in .provenmap/config.json beside it; a credential field left in config.json is ignored, and /status says so.

/login writes both files. /configure validates manual values. For CI, use PMAP_BINDING_TOKEN, PMAP_API_SECRET, PMAP_BOARD_SLUG, PMAP_BRANCH, and PMAP_BASE_URL. Environment values take precedence.

The code and connect plugins never read MCP tokens, update host MCP config, or use connector URLs.

The MCP access token: pick one of three

The architect 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.

Why the connector URL includes its key

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

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

Warning

That URL is the secret. Anyone who has it gets everything the token grants. Treat it exactly as you would treat the token: do not 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

Use this table before you set anything up.

On desktop, start with /login. Other environments may require the portal path because of browser, environment, or network limits.

Tip

Start an integration with a read token restricted to one board. 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 Architect access, and the next call made with that token gets a 401. That list holds every token for the workspace, including board-restricted ones. Tokens from /login appear in the same list, so you revoke them in one place regardless of how they were created. Signing out of the architect 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. Open the binding's credentials dialog on the Bindings card and revoke its row under Connections. You can also use Plugin connections on the command center's Architect access sheet. Both places show whether each credential is never used, active, stale, or revoked.

The code and connect plugins' /logout also revokes that machine's credential on the server. Binding credentials do not expire, so revocation ends their lifecycle. never used means the credential was issued but never connected, usually because setup did not finish on that machine.

What's next