DEVELOPER DOCUMENTATION

Connect with browser login

Authorize the OpenTrain CLI and MCP from your browser without copying an API key. Resume login, inspect the selected account, and revoke access safely.

Use browser login to connect an agent to an existing OpenTrain account. You approve access in OpenTrain; the agent never needs your password or a copied API key. This is different from registering a new agent account.

Browser login requires CLI or stdio MCP 0.27.0 or later and is enabled on https://app.opentrain.ai. If a deployment answers browser_login_not_enabled, new browser logins are switched off there. Existing API keys keep working, and repeated login attempts do not enable the feature.

Start from the CLI

Install or update the official CLI:

npm install -g @opentrain-ai/cli
opentrain --version
opentrain auth login --no-wait --json

The result contains a verification URL, matching user code, expiry and a local loginId. Give the human the verification URL and code. They can open the link on a phone or another computer, sign in to OpenTrain, check the code, and review the requested workspace and permissions before deciding whether to approve. Opening the link alone does not authorize anything.

The CLI may run over SSH or on a remote agent host. The human does not need access to that host, a localhost callback or a Vercel account. OpenTrain approval links use https://app.opentrain.ai by default.

After approval, resume the same login:

opentrain auth login wait --login-id <LOGIN_ID> --timeout 120 --json
opentrain auth status --json
opentrain capabilities --json

Verify the account, workspace and credential source before doing project work. A successful browser approval does not grant access to every workspace or operation: normal account, membership, scope and feature rules still apply. An AI trainer uses the WORKER lane with their AI trainer permissions; selecting a lane never grants a role.

For narrower access, request it when starting the login:

opentrain auth login --lane EMPLOYER \
  --scope "jobs:read messages:read" \
  --device-label "Project research agent" --no-wait --json

Resume instead of starting over

opentrain auth login status --login-id <LOGIN_ID> --json
opentrain auth login wait --login-id <LOGIN_ID> --timeout 120 --json
opentrain auth login cancel --login-id <LOGIN_ID> --json

PENDING is not a successful login. A wait timeout keeps the local handle resumable until its reported expiry. Respect the returned polling interval and retry guidance; do not create a new login for every poll or temporary error. Start a new login after denial or expiry, or when the human explicitly requests one. auth login cancel removes only the local pending handle; it does not revoke a completed session or invalidate the server code before its original expiry. Use logout or Settings to revoke an approved session.

Without --no-wait, the CLI waits up to --timeout (600 seconds by default) and sends progress to stderr. --open explicitly opens the approval page on the CLI host; leave it off when the human is on another device. Machine results stay on stdout.

Use the same session with local MCP

The CLI and stdio MCP server share the selected credential profile when they run as the same operating-system user with the same configuration directory. After CLI login, configure the MCP server without a token in its environment:

{
  "mcpServers": {
    "opentrain": {
      "command": "npx",
      "args": ["-y", "@opentrain-ai/mcp"]
    }
  }
}

Alternatively, ask the stdio agent to call opentrain_auth_login_start, show the returned link and code, and resume with opentrain_auth_login_status using the same loginId. Verify the selected account with opentrain_auth_status. These tools do not create a new OpenTrain account.

Explicit API-token environment variables take precedence over a saved browser session. Inspect credential-source diagnostics if CLI and MCP show different accounts. Do not remove or replace an existing token without confirming which integration uses it. Separate containers and OS users do not automatically share a profile.

Connect hosted MCP

Hosted MCP uses your client’s OAuth connection flow for https://app.opentrain.ai/mcp. It does not read the local CLI profile or use the stdio login tools. Follow the client’s remote-server setup and complete OpenTrain’s explicit consent page.

The client must support authorization code with PKCE S256, resource binding, and either a valid HTTPS Client ID Metadata Document or an exactly registered client. Support for arbitrary MCP transports alone does not prove compatibility with this authorization flow. Check your client’s current capabilities; do not invent a client ID, callback URL or client secret to work around a refusal. The deployed protocol is documented in OpenTrain’s auth.md.

The public documentation MCP at https://www.opentrain.ai/docs/mcp is a different, read-only service. Never send your product credentials to it.

Session security and logout

The official clients keep rotating credentials and pending-login secrets out of command results. The headless file store uses a private directory and files; protect that OS account and do not copy its credential files into a repository, chat or log. Browser sessions are bound to their issuer and resource, so changing --base-url does not authorize sending a production session to another server.

Refresh is automatic. It does not authorize blindly retrying a message, payment or other uncertain write. Keep using the operation’s idempotency key and readback or receipt workflow.

opentrain auth logout --json

Browser logout revokes the selected session and clears its local credentials. If remote revocation cannot be confirmed, follow the returned recovery guidance; local removal alone is not proof of server revocation. You can also inspect and revoke your own connections in OpenTrain under Settings → Connected agents (the Developer tab for employers, the API keys tab for AI trainers). Existing unrelated API keys are not revoked by browser logout.

Full access still means eligible self-service permissions. Restricted admin permissions require independent eligibility and explicit consent. Browser login never replaces human approval for protected financial actions.

SDK integrations

TypeScript SDK 0.25.0 or later accepts a token-provider callback through apiToken. Your application owns the OAuth flow, secure storage and refresh; the SDK does not open a browser or read the CLI’s private credentials. Static API tokens remain compatible. Never expose refresh tokens to learner content, tool results or application logs.

See Authentication, CLI configuration, and MCP setup for the alternative credential paths.