Accounts and access
Registry roles, invitations, password reset, access tokens, and the scopes each credential carries.
Roles
A registry has two roles.
| Role | Can |
|---|---|
admin | Everything a member can, plus publish, invite and manage users, and edit or delete any custom preview |
member | Sign in, read through MCP and the assistant, create access tokens, and save custom previews |
The first administrator comes from the installer. A registry always keeps at least one active administrator: the last one cannot be demoted or deactivated, and nobody can deactivate their own account.
Users
Administrators manage users under Account → Users:
- Invite a user with an email and a role. The invitation link is valid for 7 days.
- Change the role between admin and member.
- Deactivate or reactivate a user.
- Resend an invitation, or send a password reset link (valid for 1 hour).
With email configured, the registry sends these links. Without it, the administrator sees each link once and delivers it by hand, and self-service password reset is not available.
Access tokens
Every member creates their own tokens under Account → Access tokens. A token starts with hnd_,
works only on the registry that issued it, and expires after one year. Give each token a name and an
access level. The list shows each token's expiry, and you can revoke a token there.
| Scope | Label | Allows | Who can create it |
|---|---|---|---|
registry:read | Read | Check out, MCP, the read side of every API | Any member |
previews:write | Custom previews | Read, plus create and change custom previews. Cannot publish. | Any member |
registry:write | Read/write | Read, publish, and save custom previews | Administrators only |
previews:write was added in 2.1.0 so a coding agent can save previews without publish rights.
Credentials the API accepts
| Credential | How it is sent | Scopes |
|---|---|---|
| Access token | Authorization: Bearer hnd_... or X-Handoff-Api-Key: hnd_... | The token's scope |
| Device login | Saved by handoff-app login, sent like a token | The user's role: admin gets all three scopes, member gets registry:read and previews:write |
HANDOFF_SYNC_SECRET | Same headers | Read and write, deployment-wide, with no user behind it |
| Browser session | Cookie, after sign-in | The signed-in user's role |
HANDOFF_SYNC_SECRET is optional. Set it on the registry, and on a workspace or CI job only when no
token or login is available.
Your account
- Profile: display name and avatar URL.
- Access tokens: create and revoke tokens.
- AI providers: your own keys for AI connections that ask for one.
- Users: administrators only.