Authentication

Sign in once and use the same user identity across Synth workflows.

Create an account, then sign in from the CLI. You only need to do this once on each machine.

Sign in

synth login
synth status

synth login opens the Synth app in your browser. Approve the sign-in, then use synth status to check your account. The CLI stores your sign-in locally without printing the access token.

For a remote machine without a browser:

synth login --no-browser

Open the displayed URL on any device and enter the short verification code. The CLI only needs outbound HTTPS; it does not start a callback server or require an SSH tunnel.

Switch accounts or organizations

Refresh the current user’s organization context:

synth login --reauthenticate

To switch to a different user:

synth logout
synth login

Automation

Use synth login for interactive work; you do not need to create an API key or supply your user UUID. For CI, use a user-scoped credential supplied by your Synth administrator. Keep it in your CI secret store and expose it only to the process that runs Synth.

The current release requires the UUID-valued owner alongside an opaque personal access token:

export SYNTH_ACCESS_TOKEN="<customer-token>"
export SYNTH_USER_ID="<customer-user-uuid>"

A JWT carries its owner subject and does not require the separate variable.

Use a user-scoped credential for customer commands. Never place access tokens in a project .env, command history, documentation example, or task archive.

Troubleshoot login

Symptom	What to do
already_authenticated	Your cached identity is still valid. Use synth status.
Wrong organization	Run synth login --reauthenticate after selecting the organization in the Dashboard.
Wrong user	Run synth logout, then sign in again.
Remote browser did not open	Use synth login --no-browser.
Managed command reports service-key auth	Sign in through synth login; do not substitute a service key.

Run the quickstart

Choose an existing task, launch it with an explicit agent, and inspect the outcome.