OpenCode sign-in guide.

Auth method matrix.

Four methods cover the full surface. Pick the row that matches your environment.

How to sign in, step by step.

The canonical sign-in path is two minutes from a clean install to an authenticated CLI.

Step 1 — run opencode login.

In any terminal on the workstation where OpenCode is installed, run opencode login. OpenCode prints a short device code (eight characters, alphanumeric) and a verification URL. If an org workspace is configured, OpenCode also prints the workspace slug so you can confirm you are signing in to the right tenant.

Step 2 — open the URL on any device.

Open the verification URL on any device that has a browser. That device does not have to be the same workstation running OpenCode; a phone, a tablet, or a colleague's laptop works. Sign in with the identity provider configured for the workspace, paste OpenCode, and approve the session. If the workspace uses SAML 2.0 or OIDC SSO, the identity provider redirects you through its own flow first.

Step 3 — approve and verify.

The browser confirms that the device has been paired and OpenCode finishes the pairing within a few seconds. OpenCode prints the signed-in identity, the org slug, and the token expiry. To double-check, run opencode whoami; it prints the same information on demand. The refresh token lands in the OS keychain (Keychain on macOS, Credential Manager on Windows, libsecret on Linux) so OpenCode can rotate the access token without another sign-in.

Token lifetime and rotation.

Access tokens have an eight-hour lifetime by default. That is short on purpose: if a workstation is lost, the token the attacker could steal from the keychain is not a multi-day bearer.

Refresh tokens have a thirty-day inactivity window and rotate on every use. A refresh token that has not been used for thirty days is auto-expired upstream, so a stale laptop in a drawer does not linger as a valid session. A refresh token that has been used within the window extends for another thirty days. Org administrators can shorten both windows through the workspace policy in the admin console; the defaults are the upper bound.

Rotation is invisible to the developer. OpenCode silently asks for a fresh access token whenever the current one is within fifteen minutes of expiry. The only time a developer notices rotation is when the refresh token itself has expired, in which case OpenCode prints a short message and asks for opencode login again.

SSO pointers.

Org workspaces on the managed team add-on support SAML 2.0 and OpenID Connect.

SAML 2.0 is configured from the admin console. Upload the identity provider metadata XML, map the display-name and email claims, and turn on the SAML toggle. OpenCode picks up the workspace redirect without any extra flags. OIDC is configured the same way; paste the OIDC discovery URL and the client identifier, and OpenCode handles the rest. The documentation hub has a per-provider walk-through for the common providers.

Org workspaces.

An org workspace is a group of users with shared policy: SSO, RBAC, allowed models, sandbox defaults, and an audit log. Org workspaces are provisioned on the managed team add-on and are addressed by a short slug in OpenCode login URL. The slug lives in the config file, so a developer who sets it once never has to remember it again.

Workspace policy covers sandbox defaults and model allow-lists. If a workspace policy says "no cloud models in this workspace," OpenCode greys out cloud adapters at startup and routes prompts to the configured local Ollama. If the policy says "require MFA for production repos," OpenCode re-checks the identity provider's MFA claim on refresh and denies the prompt if the claim is missing.

Signing in on a headless or air-gapped host.

The device-code flow is tolerant of headless workstations because the browser can live anywhere. Ninety-five per cent of headless cases fit that pattern. For the remaining cases — air-gapped hosts that cannot reach any browser-capable device — the long-lived API key is the right fit.

An administrator provisions an API key in the admin console, scopes it to the right workspace and the right repository policy, and delivers it to the host through the existing secrets channel. The key goes in ~/.config/opencode/config.toml under the auth block. OpenCode uses the key directly, skips the device-code flow, and logs the key usage to the audit stream. Keys are rotated on the administrator's calendar; the default ceiling is ninety days and the hard maximum is a year.

API keys are not a fit for interactive workstations. Use them for CI runners, batch hosts, and air-gapped developer boxes, and stick to the device-code flow everywhere else. The federal open-source policy framework codified at code.gov and in agency supplements such as the Department of Energy open-source software policy is a useful reference for teams that have to justify API key lifetime decisions in writing.

Signing out and revoking devices.

Run opencode logout. OpenCode revokes the refresh token upstream, deletes the keychain entry, and removes any cached session from the filesystem. The access token is not revoked directly — it expires on its own within eight hours — but the refresh token it depends on is gone immediately, so the device cannot extend past the current window.

To revoke a device remotely, use the admin console. The device list shows every active refresh token for the org, including the device fingerprint, the last-seen timestamp, and the operating system. Click revoke to kill the refresh token immediately. OpenCode on that device will ask for a fresh opencode login the next time it tries to rotate.

The device-code flow saved us a training doc. Every developer on the team ran opencode login, opened the URL on their phone, and was authenticated in under two minutes. The thirty-day refresh window matches our laptop rotation policy almost exactly.

— Johanna F. Obermeier, Developer Advocate, Orinoko Data

Related auth and access pages.

Jumps into deeper references across opencode.gr.com.