Authorization

A human key identifies you

An ordinary Duet key identifies a person. It is not bound to a workspace or a saved list of permissions. CLI login, REST requests and Mac sync use that same identity; current workspace membership and role determine what each request may do.

Joining a workspace makes it available to your existing key. Leaving removes access, and a role change changes allowed operations without replacing the key. Named keys can be revoked separately, but they all use this same credential model. The CLI saves one login in ~/.duet/config.json.

Workspace selection is an operation parameter

Select the workspace in a resource address or request, rather than signing in again for each one. GET /v1/whoami returns your reachable workspaces and their current roles. Its effective scopes are a projection of that access, not permissions stored on a human key.

The capability vocabulary still names what an endpoint requires:

ws:acme:files:read
ws:acme:files:write
ws:acme:apps

For human callers Duet derives those capabilities from the current role. A refused operation needs a membership or role change; requesting a more powerful human key does not change access.

Delegated credentials retain their boundaries

An OAuth grant or installed app credential has its own explicit workspace and capability boundary. Use only the authority the integration needs. The same-workspace admin capability satisfies other capabilities, so reserve it for an integration that actually needs administration.

OAuth client registration validates and stores the client identity. The grant keeps that identity and the authorized workspace snapshot; consumers do not refetch mutable client documents while listing grants. Account operations require a human credential rather than an app or OAuth grant.

App declarations become local runtime keys

An app registration declares bare capability names in apiScopes; it does not contain a secret. Use only the capabilities required by API routes the app's server calls, or [] when it calls none. Apps cannot declare admin.

For a non-empty declaration, Duet mints a hidden app credential bound to that app row and workspace. The spawned service receives it as DUET_APP_API_KEY beside DUET_API_URL; install commands do not. A shared or installed copy gets a key minted by its recipient workspace, so source and shares never transport authority.

The platform rotates the key when its declaration changes or the cached credential needs refresh, then restarts only that app to replace its environment. Disabling or deleting the app revokes the credential, and re-enabling never resurrects the old key. App code should read the environment and keep the value in memory, never source, .env*, SQLite, logs, or a drive path: the drive syncs to devices and can be shared or published.

There is no app-install consent grant alongside apiScopes. Duet displays declarations, warns on elevated capabilities, and treats disable or uninstall as the workspace's revocation control. This keeps one authorization fact: the live app row and its declaration.

A sync machine identifies a computer

duet sync uses your ordinary saved login. The Mac also has a non-secret machine ID and its own Syncthing certificate pair. Those describe the computer; they are not a second login or a grant attached to your key. Two Macs can use the same human key and still have separate machine identities.

The daemon mirrors workspaces where your current role permits writing. Joining, leaving and role changes update that set. Replacing the human key preserves the Mac identity and certificate. Removing a lost machine detaches its mirrors without revoking your login on other computers.

Machine operations are described under mirror devices. File activity uses mirror:<machineId> and resolves that identity to the machine's user, including after removal. Replication reads do not flood each file's seen-by history; the machine's last-use time is the read-side signal.

Store, inspect and revoke the login

Use Authorization: Bearer <key> over HTTPS. Keep keys out of source and logs. The CLI's saved configuration uses owner-only permissions; explicit environment overrides remain available for programmatic clients. A key's duet_sk_ prefix helps identify its format but is not authentication.

List or revoke named human keys in the app's key settings or through the user API-key endpoints in the reference. Revoking a key refuses subsequent requests through ordinary authentication. Removing a machine and revoking a login are separate operations with different consequences.