Authentication

Every request to Synq has to answer one question first: who are you? Synq accepts four different ways to answer it, and which one applies depends on where the request comes from: a browser tab (the desktop app counts as one), a script, an AI agent, or a local single-user instance talking to itself. This page walks through each one.

The four ways in

A single request uses exactly one of these. Synq checks for a Bearer token first; if there isn't one, it looks for a session cookie; if there's neither, it falls back to the loopback path (and only if that mode is turned on).

Session cookies (the dashboard)

When you sign in to the dashboard, Synq gives your browser a signed, httpOnly session cookie. "httpOnly" means JavaScript running in the page cannot read it, so even if a bad script somehow ran on the page, it couldn't steal your session. The browser sends the cookie automatically on every request; you never handle it yourself.

On a Synq install the cookie is named synq.session_token. It belongs to the panel's host, so when the panel moves to a new address everyone signs in again there.

Two-factor authentication

Password sign-in can ask for a second step: a 6-digit code from an authenticator app, or one of 10 single-use backup codes. Each person turns it on for their own account under Settings, Security & 2FA, and can trust a device for 30 days. If the owner loses both, synq reset-admin-password on the server resets the password and turns two-factor off. Tokens and MCP clients never ask for a code. Full steps: Two-factor authentication.

Personal access tokens (Bearer)

A personal access token (PAT) is a long string you send in the Authorization header to prove who you are without a browser:

Authorization: Bearer synq_pat_…

Every token looks like synq_pat_ followed by a 43-character random secret (256 bits of entropy). Synq stores only a SHA-256 hash of it: the plaintext is shown to you exactly once, at creation, and can never be retrieved again. Tokens created by earlier versions of Synq start with a different prefix and keep working until they expire or you revoke them. A token always acts as the person who created it and carries that person's role, unless you narrow it (see below).

Create one

In the dashboard, open Settings, API tokens and use the Personal Access Tokens section:

1. Type a name (for example "MCP client").
2. Pick an expiry: No expiry, 30 days, 90 days or 1 year.
3. Optionally tick Read-only, and Limit to specific resources to choose the resources it can reach.
4. Press Create token and copy it: this is the only time it's shown.

The list shows each token with read-only and scoped badges, when it was last used, when it expires and how many calls it made, with a Revoke button.

From the terminal:

# A full-access token that acts as you
synq token create "my laptop"

# A read-only token that expires in 90 days
synq token create "ci-readonly" --read-only --expires 90

# A token scoped to one project (read + write only on that project)
synq token create "deploy-bot" --grant project:proj_123:read,write

synq token list      # your tokens (never shows secrets)
synq token revoke <id>

The request body behind the create call:

Two ways to narrow a token

• Read-only: the token can call read endpoints, but any mutating request is refused with 403 TOKEN_READ_ONLY. Great for dashboards, monitoring, and CI that only needs to look.
• Scoped: instead of acting with your full role, the token is confined to a specific list of resources you grant it (a project, a server, a repository, …), each with read, write, or admin. A scoped token acts as a restricted principal: it can do less than you, never more. You can only grant access you already hold yourself; the server checks this before minting.

MCP OAuth (AI agents)

Synq is a standards-compliant OAuth 2.1 server for the Model Context Protocol (MCP), the way AI agents call tools. An MCP-capable client (Claude, Cursor, …) points at https://app.<domain>/api/mcp, and the handshake is automatic: the first unauthenticated request returns a 401 pointing at /.well-known/oauth-protected-resource, the client registers itself, runs the PKCE authorize flow (Proof Key for Code Exchange, a way to complete OAuth safely without a stored client secret), and you approve it on a consent screen in your browser.

That consent screen is where you set the agent's limits: read-only and/or a specific set of projects, servers and repositories. Your choices are saved as the client's binding and enforced through the exact same grant model as a scoped PAT. An OAuth token that somehow skips consent has no binding, and is therefore denied everything: there is no "authenticated but unscoped" state. Tokens are also bound to the endpoint address they were issued for.

You manage connected agents under Settings, MCP, where you can see each client, change what it can reach (Edit access), see what it did (Activity) and disconnect it (which revokes its tokens immediately). Clients without OAuth support can instead authenticate with a plain PAT as a bearer credential.

Zero-auth loopback mode

An API that runs on your own machine, just for you, can skip the login. In zero-auth mode the API auto-provisions a single local admin user (Local User, owner of a personal workspace) and treats local traffic as that user. No password, no cookie to manage.

This is safe only because it is gated, and every gate must pass:

On a normal self-hosted install this path is never even reached: the auth mode defaults to local, so a missing session is a plain 401. Turning it on is a deliberate operator choice (auth mode none and SYNQ_ALLOW_ZERO_AUTH=true), and even then the loopback check keeps it usable only from the machine itself. A request arriving through a network reverse proxy carries the proxy's address as its TCP peer, not loopback, so it is refused.

Synq recognizes three auth modes overall:

• none: zero-auth loopback, described above. Never used by a CLI-started or public instance.
• local: standard login required (email + password via Better Auth, with optional two-factor). Default for a fresh self-hosted install, and always used for CLI (synq up) and public instances.
• cloud: signs in with a hosted-cloud account instead of a local one. It belongs to the hosted cloud, which is switched off in Synq, so a Synq install never uses it.

Where credentials live

Synq keeps secrets where they're safest instead of copying them around:

• PAT secrets are stored only as a SHA-256 hash; the plaintext exists just once, in your clipboard.
• Two-factor secrets and backup codes are stored with the account in Synq's database; synq reset-admin-password deletes them for the owner.
• GitHub Apps are registered by each workspace in Settings (see Self-hosted GitHub Apps); each private key, client secret, and webhook secret is stored in a versioned AES-256-GCM envelope and is never returned by the API. The legacy process-environment configuration remains supported. Every App path mints short-lived, repository-scoped installation tokens.
• Per-project git tokens and environment secrets are encrypted at rest with the install's BETTER_AUTH_SECRET. Keep that key safe: panel backups can include it for a restore.

Revocation

• A token: synq token revoke <id>, or the Revoke button in Settings, API tokens. It stops working on its next request.
• An MCP client: disconnect it under Settings, MCP: its issued tokens are revoked and the consent is dropped, so reconnecting re-prompts.
• A person: removing a member ends their access; their session stops working on its next check.

Errors you might see

Related guides