Staff

Staff are the people who run a site day to day: they open its private paths, such as /admin/, and nothing else. A staff member is not a collaborator. They cannot edit, publish or read the site through the API.

The staff list is about running the site. Owner and collaborator are about building it. They give no labels and no permissions: for those, the owner adds them to the staff list too. A private path can still let a role in by name.

The site declares its private paths, and the roles or labels each one needs, in clave.site.json. See Code in a site.

Add or change a staff member

POST /v1/sites/{id}/staff. Only the owner may call it.

{ "email": "desk@example.com", "labels": ["front-desk"], "permissions": ["payments:refund"] }

The person needs a Clave account first. Call it again to change the labels or the permissions.

labels are the site's own words. The site's code reads them and decides what each one may do with the site's own data.
permissions are the platform's. payments:refund lets the person give the site's money back through the site's code. The owner gets it the same way: add the owner's own address with the permission.

GET /v1/sites/{id}/staff lists them. DELETE /v1/sites/{id}/staff/{account_id} removes one. A removed person keeps their open page for up to an hour, but every refund reads the staff list at that moment, so they lose money rights at once. A change of labels reaches the person at their next sign-in.

How staff sign in

A staff member opens a private path, for example /admin/.
The site sends them to Clave to sign in with their own account.
Clave sends them back, and the site keeps a session on its own address for one hour. /clave/signout ends it.
If the path names roles or labels, a person with none of them gets a

On each request, the site's code gets a Clave-Identity header: a signed token that says who the person is, their role, their labels and their permissions. It lives five minutes. The site's code reads it for "who is this", and forwards it to a guarded call:

POST /v1/runtime/payments/{id}/refund with the site key, the Clave-Identity header and { "amount_minor": 1000 }. The platform checks the token, then the person's permissions now, then that the payment is this site's and the amount is not more than was paid. See Runtime.

An action gets the header too, because the session works on every path. Check it in the action: anyone can post to /_actions/name.

The Clave-Identity token

The token is v1.<payload>.<signature>. The payload is base64url JSON with no padding:

Field	Holds
`kind`	`identity`
`account`	the person's Clave account id
`email`	the person's mail address
`site`, `host`	the site and the hostname the token is for
`role`	`owner`, `collaborator` or `staff`. It gives no permissions: the site's code decides what it means
`labels`	the site's own labels, from the staff list
`perms`	the platform permissions, such as `payments:refund`
`via`	`browser` or `agent`
`exp`	when it stops being valid, in Unix seconds

The signature is the platform's own. The site's code cannot check it, because it does not get the key. It does not need to: on every path, public ones too, the platform removes a Clave-Identity that a visitor sent. The header the site's code gets is always the platform's. Read the payload, and check exp and host.

The token says who the person was when it was made. For money, the platform reads the staff list again at the call.

POST /v1/site-signin/exchange is the dispatcher's own call. It takes a platform signature, and nothing else can call it.