CLI Authentication
How to authenticate the MarkDocket CLI using browser OAuth (with dynamic client registration and PKCE) or a personal API key, and what capabilities each authentication mode enables.
The MarkDocket CLI supports two authentication modes: browser OAuth and personal API key. Each mode grants access to the same tool catalog but uses a different execution transport and has slightly different scope.
Browser OAuth
Run the login command to open a browser window and complete authentication through your MarkDocket account:
markdocket loginThe CLI guides you through the following steps automatically:
- Discovers the authorization server configuration from the MarkDocket API.
- Dynamically registers a new OAuth 2.1 client for the current session — no static client ID is embedded in or distributed with the CLI package.
- Opens your browser to the MarkDocket authorization page, where you can review and selectively grant or deselect optional permission scopes before approving access.
- Listens on a loopback port to receive the authorization code.
- Exchanges the code for an access token using PKCE (Proof Key for Code Exchange).
New to MarkDocket?
markdocket login again. The login flow does not automatically resume after account creation.What browser OAuth enables
Access tokens issued through browser OAuth are resource-bound to the MarkDocket hosted MCP endpoint. All tool calls made in this mode route through that endpoint rather than directly to the API. This means:
- You can use all tools available in the public tool catalog.
- Billing, device pairing, and credential management operations are explicitly excluded from MCP tokens — these always require a browser session in the web app.
- The
openidscope is always granted and cannot be deselected.
Personal API Key
If you prefer not to use browser-based login, you can authenticate with a personal API key generated from your account settings.
markdocket login --key YOUR_API_KEYYou can generate a personal API key from Settings → API Keys in the MarkDocket web app.
What personal API key mode enables
Personal API key sessions call the MarkDocket API directly using a bearer token. This gives you access to the same tool catalog as browser OAuth. Tool calls made with an API key are still routed through the cataloged tool registry — only routes explicitly registered in the tool catalog are reachable from an external token.
Comparing the two modes
| Browser OAuth | Personal API key | |
|---|---|---|
| Authentication flow | Browser redirect with PKCE | API key passed at login |
| Client registration | Dynamic per-session (RFC 7591) | Not applicable |
| Execution transport | Hosted MCP endpoint | API bearer token |
| Tool catalog access | Full public catalog | Full public catalog |
| Billing / device / credential actions | Excluded from token scope | Excluded from token scope |
| Best for | Interactive developer workflows | CI, scripting, non-interactive use |
Checking your current session
markdocket whoamiThis command prints the currently authenticated user and the active authentication mode.
Logging out
markdocket logoutThis revokes the stored session credentials locally. For browser OAuth sessions, the access token is also invalidated server-side.
Security notes
- PKCE: Browser OAuth uses a 48-byte random verifier with the S256 challenge method. State is also randomized per session to prevent cross-site request forgery during the redirect.
- Dynamic client registration: A fresh OAuth client is registered for each login session, scoped exclusively to the loopback redirect URI opened for that session. No long-lived client secret is stored in the CLI.
- Tool catalog provenance: Regardless of auth mode, the CLI can only reach API routes that are part of the published tool catalog. Routes outside the catalog remain unreachable from CLI tokens.
- Personal API keys: Treat your API key like a password. Rotate it immediately from Settings → API Keys if you believe it has been compromised.
CLI Overview
Introduction to the @markdocket/cli npm package — installation, available commands, how the tool catalog is derived from the agent registry, authentication methods, and the MCP server surface.
Invoking Tools from the CLI
How to invoke IP research tools directly from the terminal using `markdocket call <name>`, including available tools, passing arguments as JSON, and reading structured responses.