Skip to main content

​
What a token can do

A user API token is a complete credential. Set OHMYHOST_TOKEN and the CLI, the MCP server and the REST API all accept it — no login, no browser, no saved session. Where the variable is set it wins over any saved login. New tokens do not expire until you revoke them. A token acts only in the workspace it was created for, with every action permission your account has there except workspace and token management. Membership and role still apply. A command naming another account through --organization, --profile-name, OHMYHOST_PROFILE or a checkout linked to another organization stops as environment_token_context_mismatch before sending. Six commands require an interactive login: organization create, organization list, organization use, token create, token list and token revoke. CLI/MCP return interactive_login_required while OHMYHOST_TOKEN is set. Run these in a process without that variable; direct REST organization creation with a token returns 403 forbidden. ohmyhost login and ohmyhost logout also refuse to run while OHMYHOST_TOKEN is set, and exit with environment_token_active. Run all of these from a shell where the variable is unset; your token file is not touched.

​
Sign in interactively

Open the returned link and sign in or sign up. Direct signup, including a malformed referral source, creates a Free My workspace; a valid referral may add its configured benefit. ohmyhost whoami --json confirms the actual selection. Reuse an existing workspace. With several organizations, bind an unbound login using ohmyhost organization use --organization ULID --json; if none exists, use organization create. A saved login keeps its workspace (profile_organization_fixed): add a separate login with ohmyhost login --organization ULID --json for another workspace. Existing customers can return through login. Sessions are kept in the operating system’s credential store, also read by local MCP. On credential_store_unavailable, unlock the desktop store and retry; a headless/CI host can use a private OHMYHOST_TOKEN from the portal instead. logout --json removes the selected saved login; --revoke also ends its server session. Neither revokes an API token.

​
Several accounts on one computer

Each saved login identifies one user in one organization and platform. List them with ohmyhost profile list --json; select one with --profile-name NAME, MCP profile_name or OHMYHOST_PROFILE=NAME. A checkout linked to that organization can choose the login automatically, including with explicit --project. Otherwise multiple plausible logins require an explicit selection (profile_selection_required). Verify whoami before changing a project. Add a login for a different user/workspace with ohmyhost login --organization ULID --user USER_ID --json. Do not rename or move an existing login to change accounts. Names use lowercase letters, digits, hyphens and underscores, start with a letter or digit, and are at most 63 characters. A name conflict preserves the existing login; choose an unused --profile-name. The first command after upgrading a legacy login needs network access to bind its named profile. A portal prompt naming only a user can match or create an organizationless login; select/create the intended workspace afterward. Account IDs in a prompt identify context, never grant authority.

​
Create a token in the portal

Open the profile menu → API Tokens. Choose the organization, enter a descriptive name and create the key. Copy its full value once into your automation platform’s secret field or a private env file. The portal subsequently shows metadata only. New user API tokens have no expiry and remain valid until revoked. Existing tokens retain the expiry recorded when they were created. Browser and CLI login sessions have separate lifetimes.

​
Create a token with the CLI

Use an interactive-login process without OHMYHOST_TOKEN set:
Retain the same request key for an interrupted request. Creation writes the new secret to the selected private file; it does not overwrite existing credentials. Ignore the file in Git and load it into the CLI/MCP process using your runtime’s env-file support. Never copy the value into a prompt, URL or application source.

​
Connect an automation to project data

Use the token in your automation platform’s secret field and send it as a Bearer header to the database API. Select the project and dev or prod explicitly. Owner project permissions are required for these reads and writes; creating a token does not grant additional permissions or bypass the application’s row-level security. For each deliberate write, retain one idempotency key and inspect its receipt before proceeding. Never create a new key automatically after an unknown write outcome. Keep the token itself out of URLs, prompts, SQL parameters and application source.

​
Use and revoke

Send Authorization: Bearer with the token to the selected API origin. The key identifies its owner and organization; project IDs do not grant access. Current membership and action permissions still apply.
KEY_ID comes from the metadata list. Revocation requires your interactive session and affects only that selected key. A revoked key cannot be recovered; create another when needed. API examples · MCP connection