Authentication and visibility

Browser access#

Open Account in the shared header for sign-in, sign-out, and User settings. Settings shows the current browser account, your appearance preference, and authentication guidance. Sign-in is shown only when the workspace has an identity provider configured.

When service sign-in is configured, protected pages use the organization's browser identity provider. Mockspace validates the returned identity and creates its own HTTP-only session. Public website pages and documentation remain separate from project data.

Being signed in does not make every private record visible. A draft or request carries its own owner and private or project visibility. A private record answers another user like a missing record so its existence is not disclosed.

CLI personal login#

Authorize a computer with:

mockspace login --service https://mockspace.ynext.co
mockspace whoami --service https://mockspace.ynext.co

The browser approval uses a short-lived, one-time code with a verifier. --no-browser prints the authorization URL and lets you paste the resulting code into a headless terminal.

Saved credentials are scoped by service origin. By default they live in $XDG_CONFIG_HOME/mockspace/credentials.json, or ~/.config/mockspace/credentials.json when the XDG path is unset. The directory and file are created with restrictive permissions. Tokens are not embedded in review URLs or returned to the agent.

Personal credentials expire. whoami prints the expiry, and the CLI warns when it is near. Run mockspace logout --service <origin> to remove one saved login from the computer.

Hosted MCP OAuth#

The hosted /mcp endpoint accepts OAuth bearer tokens issued through the service's protected-resource and authorization-server metadata. Compatible MCP clients perform browser consent and PKCE automatically after registration.

This token is distinct from a CLI personal token. The shared review URL carries context, not credentials. The hosted MCP does not expose local files.

Project creation#

Hosted MCP create_project uses the connected OAuth identity. POST /api/projects also accepts personal and machine tokens; cookie-only creation is refused. Registration does not publish source code or change a review’s visibility. See the project API.

Machine tokens#

Machine write tokens are intended for CI and controlled automation. They can publish and perform server-owned operations that an ordinary personal session cannot. Keep them in a secret store and pass them through the supported environment or x-mockspace-token header; never put them in documentation, a URL, a captured build, or agent-visible prose.

On a person's laptop, prefer mockspace login so publishes and permitted writes carry that person's identity.

CLI precedence#

For CLI operations that accept credentials, an explicit --token wins, followed by MOCKSPACE_TOKEN, machine-token environment configuration, and then the saved login for the service. logout removes only the saved login; it does not clear environment variables.

Visibility is per record#

A published trunk or PR build is normally project-visible. A chat-origin draft with an owner can begin private. The owner or an authorized machine actor can change a draft's visibility; trunk cannot be made private.

Design requests are private by default. Sharing a request is an explicit recorded change and includes its conversation and events. Sharing a resulting build does not implicitly share the request that produced it, and sharing a request does not implicitly expose every build it referenced.

Use the review's Share control or the supported CLI option instead of constructing visibility requests by hand.

Access failures#

A browser request without a valid session receives a sign-in page or redirect. A programmatic request receives a 401 response. A request for someone else's private record may receive 404 by design. An anonymous hosted MCP request receives a 401 challenge pointing to OAuth metadata.

If a saved CLI login expired, sign in again. If an automation token is refused, verify which credential source won before rotating secrets. Continue with Troubleshooting.