Authentication

Documentation Index

Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

GitHub OAuth (dashboard)

1. Redirect — clicking “Sign in with GitHub” redirects to GitHub’s OAuth authorization endpoint.
2. Authorization — you approve the Macroscope GitHub App’s requested scopes (org membership, repo access).
3. Token exchange — the dashboard backend exchanges the authorization code for an access token.
4. Session creation — a session cookie is created containing the OAuth tokens, encrypted with ECIES P-256.
5. Tenant resolution — your GitHub org memberships are checked to determine which tenants you can access.

​

Session cookies

• Encryption — ECIES P-256 (Elliptic Curve Integrated Encryption Scheme). The OAuth tokens inside the cookie are encrypted and cannot be read by the browser or intercepted by client-side JavaScript.
• Expiry — 30-day session lifetime.
• Auto-refresh — tokens are refreshed transparently before expiry. You will not be prompted to re-authenticate unless the cookie is cleared or the session exceeds the maximum lifetime.
• Scope — cookies are scoped to the dashboard domain with HttpOnly, Secure, and SameSite flags.

​

Identity tokens (CLI and MCP)

# Authenticate the CLI
murmur login

1. murmur login initiates a GitHub device flow or browser-based OAuth.
2. Your GitHub token is used to generate a Murmur identity token.
3. The identity token is stored locally (typically in your OS keychain or a secured file).
4. All subsequent CLI commands include the identity token in gRPC metadata.

​

Token management

# Check current authentication status
murmur auth status

# Re-authenticate (e.g., after token expiry)
murmur login

# View your identity
murmur whoami

​

Agent authentication

1. VM boot — the control plane provisions the VM and generates a short-lived token scoped to the agent’s session.
2. Token delivery — the token is delivered to the VM through a secure metadata channel.
3. API calls — the MCP server on the VM includes this token in all API requests.
4. Scope — the token is limited to operations relevant to the agent’s session: status updates, task management, spawning children, and uploading files.
5. Expiry — tokens have a short lifetime and are not renewable. When the agent session ends, the token becomes invalid.

• Access other tenants
• Modify catalog resources outside their scope
• Access secrets not assigned to their workspace
• Impersonate other users

​

Token refresh

​

GitHub App authentication

​

Installation tokens

• Scope — each installation token is scoped to the repositories where the GitHub App is installed.
• Lifetime — tokens are short-lived (1 hour) and requested on demand.
• Rotation — the platform requests fresh tokens as needed; no long-lived tokens are stored.

​

Event pipeline authentication

1. OIDC token — GitHub Actions generates an OIDC token for the workflow run.
2. WIF exchange — the OIDC token is exchanged for a Google Cloud access token via Workload Identity Federation.
3. Event submission — the access token authenticates the event submission to the Murmur event bus.

• No stored secrets — no Murmur API keys or service account keys are stored in GitHub repository secrets.
• Short-lived — OIDC tokens are valid only for the duration of the workflow run.
• Auditable — every event submission is tied to a specific GitHub Actions workflow run.

​

Setting up event authentication

murmur install-repo

​

Session management

​

Dashboard sessions

​

CLI sessions

​

Agent sessions