# ![Synkro package](https://docs.synkro.sh/parcel-favicon-32.png?v=bow-1) Synkro authentication

This guide tells agents how to register with Synkro, obtain credentials and
maintain authorized access on a user's behalf. Use the Synkro CLI for this flow.
The user verifies their email, claims the account and approves connecting you.
You cannot claim the account or approve yourself. A waitlist request or pending
registration grants no access.

## Supported authentication

| Area | Supported behavior |
| --- | --- |
| Client | The Synkro CLI manages registration, credential storage and renewal. Client developers can use the documented connection grant below. |
| Registration method | `service_auth` through Synkro connection protocol version 2. |
| User authorization | Required before credentials are issued. New accounts also require access review. |
| Credential type | Short-lived access tokens scoped to the approved user, organization and agent connection. The CLI retains private state to renew them. |
| Anonymous registration | Not supported. |
| Provider identity assertions (ID-JAG) | Not supported. |

Synkro uses its own CLI connection protocol. The commands and discovery endpoint
below describe that protocol; do not substitute registration requests from
another service. User device login is a separate flow.
Do not use the user's personal sign-in credentials to get past an agent access
restriction.

## Scopes and user approval

Scopes describe permissions. The approved connection can receive these scopes
within the user's account and organization. The service checks the permissions
actually granted on each request; this list does not grant access by itself.

| Scope | What it allows |
| --- | --- |
| `synkro:onboard` | Check whether the organization can use Synkro and verify setup progress. |
| `synkro:install` | Report this installation's integration inventory. |
| `synkro:policy` | Publish project rules and manage this installation's rule suggestions. User approval is still required before applying a proposed rule. |
| `synkro:act` | Submit governed tool calls, semantic rule checks and hook diagnostics. |
| `synkro:evidence` | Submit feedback and read onboarding evidence, events and traces belonging to this connection and installation. |

These permissions do not grant organization-owner powers or access to other
installations' evidence. Payment, logout and uninstall requests each require
separate user approval through Synkro. Connecting an agent does not approve a
rule or a payment.

## Before registering

Downloading the CLI is free and needs no account or card. Check what is installed:

```sh
command -v synkro
synkro --version
synkro onboard --help
synkro onboard claim --help
synkro onboard verify --help
```

If missing, follow the binary installation steps at
https://docs.synkro.sh/onboarding/install. Use the account claim steps below to
request your connection rather than signing in on the user's behalf. On macOS
with Homebrew, install with:

```sh
brew install synkro-sh/tap/synkro
```

For an existing Homebrew installation, use `brew update` and
`brew upgrade synkro-sh/tap/synkro`. On Linux, use the documented direct download
and verify its checksum. Do not invent a release URL, skip checksum verification
or replace a development build without approval.

Run the help checks again after updating. Continue only if `onboard` supports
`start`, `status`, `resume --wait-seconds`, `claim --new-link` and `verify`.
If a command is still missing after updating, stop and report the version and
error.

## Discovery

Use the App origin that served this guide, with no `/auth.md` path. Set
`SYNKRO_WEB_AUTH_URL` to that origin for every setup command and resumed session.
For example, `https://app.synkro.sh/auth.md` uses `https://app.synkro.sh`, while
`https://app.sandbox.synkro.sh/auth.md` uses `https://app.sandbox.synkro.sh`.
Confirm any other origin with your administrator. Replace `APP_ORIGIN` before running:

```sh
export SYNKRO_WEB_AUTH_URL="APP_ORIGIN"
```

Keep the same service and installation directory throughout setup. Do not switch
environments to get around unavailable signup, a declined request or a saved-state
mismatch. Saved attempts remain bound to their original service.

The CLI fetches
[`GET /api/onboarding/agent/discovery`](/api/onboarding/agent/discovery) on this
App origin. It returns the configured App, API resource, credential issuer,
registration endpoints, supported scopes, this guide and the package logo.
The `resource` is the protected API; the App hosts user approval and registration.
This is Synkro's CLI connection protocol. Use the CLI for ordinary setup;
client developers can use the connection-grant profile below.

The API publishes standard protected-resource metadata at
`/.well-known/oauth-protected-resource`. Its `resource_documentation` points to
this guide; `authorization_servers` identifies this Synkro App. Fetch
`/.well-known/oauth-authorization-server` on that App origin for the supported
grant types, token endpoint and `agent_auth` registration instructions. The
metadata's `issuer` must exactly match the App origin you discovered. Metadata
also describes supported scopes, the package logo, Terms and Privacy Policy.
The CLI discovery response above includes this document's `resource_metadata` URL.

A bearer API `401` response includes a `Link` header to this guide. For query-free
requests, `WWW-Authenticate` also provides a `resource_metadata` URL for that API
path. Follow the guide to install the CLI and request access. Discovering the
service does not approve an account or connection: the waitlist, user verification
and approval steps below still apply. Anonymous registration is not supported.

### Connection grant for client developers

For ordinary setup, use the CLI commands below. If you are implementing a
client, follow this profile: `agent_auth.protocol = synkro-agent-connection-v2`.
It uses an OAuth extension grant over the same user-approved connection.
Do not substitute another service's assertion exchange or browser login flow.

1. POST JSON to `agent_auth.identity_endpoint` with `type: "service_auth"`,
   `login_hint` containing the user's email, and `client` containing
   `installationId` (a stable UUID), `harness` (`codex`, `claude_code`, `cursor`,
   `antigravity`, or `null`) and `name` (a display name or `null`). Save the
   returned `claim.token` privately. Give the user
   `claim.attempt.verification_uri` to complete access review and approve the
   connection. Registration alone grants no access.
2. POST a UTF-8 `application/x-www-form-urlencoded` body to `token_endpoint`:
   `grant_type=https://synkro.sh/oauth/grants/agent-connection`,
   `client_id=synkro-agent`, and `claim_token` containing the saved private token.
   The optional `resource` must equal the API origin in `protected_resources`.
   Omit `scope`: permissions come from the approved connection, and requests
   to change them are rejected. Use a form serializer; do not place secrets in
   URLs, prompts or logs. Do not send browser cookies or an Authorization header.
3. A successful response contains `access_token`, `token_type: "Bearer"`,
   `expires_in` (seconds remaining), `refresh_token`, the space-separated
   granted `scope`, `installation_id` and `agent_connection_id`. Treat tokens
   as opaque: do not decode them to infer identity or authorization. This
   profile does not provide OpenID Connect or client-side JWT verification.
   Call the API using `Authorization: Bearer <access_token>` and
   `X-Synkro-Installation-Id` matching the returned installation.
4. Renew at the same token endpoint with `grant_type=refresh_token`,
   `client_id=synkro-agent` and the saved `refresh_token`. Save the returned
   credentials atomically. Renewal may reuse a still-valid access token and
   does not change the approved account, installation or permissions.

`authorization_pending` (HTTP 400) means the connection is not approved yet;
retry collection no more often than every two seconds. `invalid_grant` (400)
means collection was refused: keep saved state and check the connection with
the user. For a failed or expired approval attempt, POST JSON
`{ "claim_token": "<saved private token>" }` to `agent_auth.claim_endpoint` and
give the returned `attempt.verification_uri` to the user. Revoked connections
cannot be revived this way. A lost response can be retried with the same
connection token; do not create another registration to bypass a refusal.

Malformed forms, duplicates and unknown parameters return `invalid_request`;
unsupported grant types return `unsupported_grant_type`, an unknown client ID
returns `invalid_client`, scope changes return `invalid_scope`, and a different
resource returns `invalid_target` (all HTTP 400). Rate limits return 429;
temporary service failures return 503. Back off and retry the same operation.

Logout, uninstall and payment still require their separate user approvals
through Synkro. No direct OAuth revocation, anonymous grant, password grant,
authorization-code grant or client-credentials grant is advertised. The existing
CLI uses its current JSON endpoints and does not need an update for discovery.

## Reuse existing credentials or registration

```sh
synkro whoami --json
synkro onboard status --json
```

`whoami` describes the installation's saved identity and tries to renew an
expired sign-in.
An expired token alone does not mean you need another account. If identity fields
are empty, credentials have not been loaded: resume saved setup and read its final
result. A missing setup attempt is normal on a fresh installation.

- If `credentialKind` is `human`, preserve their sign-in. Ask whether to continue
  the user's existing setup or use a separate installation for this agent. Do
  not log them out, copy their tokens or overwrite their credentials.
- If this agent has saved signup, claim or verification progress, use
  `synkro onboard resume --json`. It resumes the latest saved phase and can
  renew a connected agent's credentials. Do not submit another signup.
- If the saved email, organization or service is different, stop and ask the
  user. Do not delete private state to force a new identity.

## Register

For a fresh setup, ask the user for their email and whether they already
have an approved account. Replace `EMAIL` below. For a new applicant only:

```sh
synkro onboard start --email EMAIL --json
```

This adds the email to Synkro's waitlist; it does not need to be listed already.
We review new requests before the user can claim the account and authorize
the agent. Approval of the access request is separate from the user's
authorization. While the next action is `review_application`, use
`synkro onboard resume --wait-seconds 300 --json` to check the saved request.
If the user prefers to submit the request themselves, give them
https://synkro.sh/request-access, then continue with that same email.
Website and CLI requests join the same waitlist. Use the CLI directly when
requesting access on the user's behalf; no browser form is needed.

Optionally add `--organization "ORGANIZATION_NAME"` using a name the user
supplies. Omit it if they want to choose the name during account verification.
For an existing approved account instead:

```sh
synkro onboard claim --email EMAIL --json
```

Add `--harness codex --name "My Codex"`
(or the supported harness you actually use) when starting the claim. Confirm these
options in `--help` first. Use separate installation directories for independently
revocable agent connections; two agents sharing credentials share one connection.

### Registration status

Read `next.actor` and `next.action`. Admission reports use `status.next` when
`status` is present; claim and verification reports use top-level `next`.
Do not assume every response has the same shape or that exit code zero means done.

| Action | What to do |
| --- | --- |
| `review_application` | The Synkro team is reviewing access. Resume later; do not submit another signup. |
| `claim_account` | Give the user the returned `verification_url` for verification and authorization. |
| `retry_exchange` | Run `synkro onboard claim --json` to resume obtaining credentials from the saved registration. |
| `install` | The CLI has obtained the approved connection's credentials. Confirm the identity below, then install; enforcement is not yet verified. |
| `denied` or `expired` | Stop and contact the Synkro team. Do not create a replacement account. |

To check once or wait for access approval or account claiming for at most five minutes:

```sh
synkro onboard resume --json
synkro onboard resume --wait-seconds 300 --json
```

Choose one, not both in a loop. The CLI respects the service's polling interval.
Run one onboarding command at a time. If a background `resume` is still running,
wait for it to finish and read its result before running `status`, `claim`, or
another `resume`. A busy setup lock does not mean the account was rejected;
keep the saved attempt and do not request a new link just because it is busy.
Do not busy-poll or run onboarding commands concurrently.

## User verification and authorization

Use the returned `verification_url`, never an invented or reconstructed link.
The user verifies their email and clicks **Claim account and connect agent**.
That action accepts the displayed terms and authorizes this agent's listed permissions.
They then save a card if required. An existing customer signs in and clicks
**Connect agent** for their eligible organization. Do not use
browser automation to do these steps for them.

Do not ask for their password, email verification code or card details.
The offered $20 starter credit requires a saved card and server confirmation.
A browser return alone is not proof of credit. Do not buy usage or enable
automatic refill as part of setup.

There is no connection code to copy and no separate approval after card setup.

Finish one connection at a time for the same email, using the newest email code.
Keep the claim and card steps in the same browser with storage enabled. The page
saves the connection link in that tab before removing it from the address bar.
If it offers **Retry setup**, retry there. If it offers **Verify email again**,
the user must follow that link. Keep the same account: confirmed card setup and
starter credit are not repeated. Persistent service errors need support, not an
account deletion or repeated link renewal. Report the failure time and reference
number if shown; do not share verification codes or connection links.

### Organization selection

The user reviews the account and organization on Synkro's approval page.
When creating an organization, they confirm its name. If the page offers an
organization selector, they choose the eligible organization they intend to use.
An already signed-in account uses the organization shown on the page; do not
assume a selector will appear. If the account or organization is wrong, stop
before approval and have the user correct it. Do not invent an organization ID
or create another organization to work around access restrictions.

## Obtain and use credentials

After the user approves, resume the saved registration to obtain credentials:

```sh
synkro onboard resume --wait-seconds 300 --json
```

Wait for that command to finish and read its result. If interrupted, use
`synkro onboard claim --json` to resume the saved registration. When
`next.action` is `install`, confirm the authenticated identity:

```sh
synkro whoami --json
```

Confirm authentication succeeded, the expected email and organization,
`credentialKind: agent`, and the expected agent connection. The report includes
`agentConnectionId`, `agentInstanceId`, `agentSessionId` and `agentClient`.
Missing identity fields or a failed command are not a successful authentication.
The CLI uses the saved credentials for authorized requests; you do not need to
extract a token or construct an Authorization header yourself.

Authentication is complete when the CLI has obtained credentials and confirmed
the expected identity. Hook installation and enforcement verification are separate
steps, described under [After authentication](#after-authentication).

## Credential storage and refresh

The CLI renews short-lived access tokens as needed. Keep its saved connection
state. Use `synkro onboard claim --json` to check or renew a connected agent
online. `whoami` also tries to renew an expired token. A successful browser
approval must still be followed by this installation obtaining its credentials.
Never print, copy or edit credential files, access tokens, renewal secrets or
saved claim tokens. Do not put them or private connection links in command
arguments, logs, source files or shell history. Keep saved state through failures.

## Errors and recovery

Read the CLI's returned next action and error. Preserve the saved registration;
an authentication failure alone does not mean that another signup is needed.

| Situation | Recovery |
| --- | --- |
| Waiting for access review or user authorization | Resume the saved registration with a bounded wait. A pending registration grants no access. |
| Access token expired | Let the CLI refresh it; `synkro whoami --json` attempts renewal. Do not request another account just because a token expired. |
| Approval link expired, or the service explicitly requests a new link | Use `synkro onboard claim --new-link --json` and return the new link to the user. This renews the approval link for the saved connection. |
| Request interrupted or obtaining credentials failed | Resume the last saved phase with `synkro onboard resume --json` or the returned next action. If recovery is refused, keep state and contact support. |
| Authorization refused (401/403), wrong account or organization, invalid service, disabled signup | Stop. Ask the user or Synkro team to correct access/configuration. Do not switch identities or environments, request broader permissions or discard credentials automatically. |
| Connection expired or revoked | A new approval link cannot restore revoked access. Ask the user or support to confirm how to reconnect; do not start a replacement signup. |
| Rate limit (429) or temporary service failure (5xx) | Honor the returned retry interval when present. Wait before a bounded retry of the saved operation; do not loop signup. |
| Missing, damaged or old incompatible saved credentials | Preserve them privately and ask for reconnection help. Do not delete state or create another account to hide the error. |

To replace an expired approval link or follow an explicit new-link instruction:

```sh
synkro onboard claim --new-link --json
```

Give the returned URL to the user. If renewal is refused, keep the saved
registration and ask for help.

## Revocation and sensitive actions

If the user asks to disconnect, `synkro logout` requests their approval. Give
the returned Synkro approval URL to the user, then retry the same command. After
approval, the CLI revokes this connection and clears local credentials only when
revocation is confirmed. If confirmation fails, keep the saved state and retry
the same command; do not claim remote access was revoked. Logout is not a retry
or registration-reset step.

Agent `uninstall` and `account pay --amount` requests also require separate user
approval through Synkro. Do not approve these requests yourself or switch to user
credentials. Denial means stop. A payment receipt saying checkout opened is not
proof of payment; only confirmed payment adds funds. Other scoped commands, such
as feedback and reading your own evidence, do not require this extra approval.

## After authentication

For installation, use the connected report's `daemon_url`, not the App origin.
Confirm it belongs to this setup and replace `DAEMON_URL`:

```sh
synkro install --daemon-url DAEMON_URL
synkro status --json
```

Keep the limited connection credential. Do not use `--force`, `synkro login` or
local daemon mode as a shortcut. If installation unexpectedly requests another
sign-in, stop and inspect the saved registration. Ask the user to complete any
required hook trust and start a new agent session. See
[supported agents](https://docs.synkro.sh/reference/supported-agents).

Confirm the installation's enforcement is `active`
(`installationEnforcement.state` when present). Check semantic enforcement
separately if the rule needs it. Anonymous server health, paused enforcement or
an unavailable result is not proof of working enforcement.

Preserve the project's existing rules, manifest and lock. Follow the
[rule approval and verification workflow](https://docs.synkro.sh/prompts/references/agent-registration.md#exact-rule-approval)
and [rule format](https://docs.synkro.sh/guides/rules) to propose a rule, check its
examples and verify a harmless governed action. After following that workflow,
read the new action's evidence with:

```sh
synkro onboard verify --json
```

Get the user's approval before applying the exact rule. They may skip it without
losing access. A prior decision or a failed-open Allow is not proof that the new
rule works; report authentication, installation and rule verification separately.

## Billing and legal

Read [billing and usage](https://docs.synkro.sh/guides/billing), the
[Terms of Service](https://synkro.sh/terms/) and the
[Privacy Policy](https://synkro.sh/privacy/). Use test cards only in sandbox;
sandbox and production funds are separate.

## Contact

For help, see [troubleshooting](https://docs.synkro.sh/troubleshooting) or email
[team@synkro.sh](mailto:team@synkro.sh) with the CLI version, stage and non-secret
error or reference number. Never attach private credential files, connection
links or verification codes.