Identity and scope

Understand how users, organizations, credentials, and resource ownership fit together.

Every customer action resolves to a user identity and, when organization work is involved, an active organization scope.

Interactive use

synth login
synth status

Browser device authorization creates a user-scoped credential in the local Synth credential cache. Status commands show identity metadata without printing the bearer value.

Automation

Use a customer personal access token for headless work. Store the token and its owner UUID in your CI secret manager and expose them only to the Synth process.

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

An opaque synth_pat_... token requires SYNTH_USER_ID. The released CLI fails before sending a request when the owner is missing or is not a UUID. A JWT carries its UUID subject and does not require the separate owner variable.

Service credentials and worker tokens are not customer identities. They are intentionally excluded from the customer API and these docs.

User paths and organization authority

Some HTTP resources include /users/{user_id} in the path. The authenticated user must match that path. A valid token for another user returns a tenant-safe authorization or not-found response.

Organization-scoped mutations also require a current organization binding. A valid bearer alone does not grant access to another organization’s tasks, runs, evidence, or quota.

Credential-safe troubleshooting

Never print the token to debug identity. Use:

synth status --json

If the cached credential belongs to another Synth connection, reauthenticate deliberately for the intended service. Do not send a credential to a different or untrusted host merely to bypass a connection mismatch.