Users

View .md

Proof has no accounts, no passwords and no sign-in. A user is one of your people. Your server tells Proof who they are, and Proof records what they do in the editor.

Two ids

Every user has two ids:

Id	Example	Whose
`id`	`usr_5Kq2Lm8R`	Proof’s. It never changes, and it is what documents, seals, members, sessions and webhooks use.
`external_id`	`u_42`	Yours: whatever your product already calls this person, up to 128 characters. Unique on your platform, and you can change it.

Proof’s records refer only to its own ids, so the history of who wrote what never depends on a key you might change, and your ids, which may be emails or database keys, never end up in documents or on seals.

Keep the Proof id beside your user, the way you’d keep a Stripe customer id: a proof_user_id column is enough. When you have only your own id, look the user up by it.

Creating and updating

PUT /v1/users/external/{external_id} creates the user the first time you send an external_id and updates them after that, and returns the user with its Proof id. Call it when someone signs up, and again whenever their profile changes:

{
  "name": "Ada Lovelace",
  "avatar_url": "https://acme.com/avatars/42.png",
  "detail": "ada@acme.com"
}

Field	Meaning
`name`	How the person appears to others: beside their cursor, on comments, in the seal’s breakdown. Up to 48 characters.
`avatar_url`	Optional. A picture Proof fetches once and serves itself: PNG, JPEG or WebP, at most 1 MB.
`detail`	Optional. A second line under the name in mention lists, such as an email or a team, to tell two people with the same name apart.

A user needs a name before they can open the editor. See the Users reference for every field.

Changing your ids

If your ids change, for example in a migration or when someone switches login method, point the Proof user at the new one with PATCH /v1/users/{id} and a new external_id. Nothing else moves: documents, seals and agents follow the Proof id.

You vouch for who people are

Proof takes your word for a user’s identity. When Ada’s seal says “Ada Lovelace”, it means “Acme Notes says this is Ada Lovelace”, and the seal page says so. Proof can vouch for what happened in the editor; only you know who was signed in. The trust model covers what each side vouches for.

Name changes

Documents name people by their Proof id, not by the name they had when they wrote. When you change a user’s name or picture, every open editor shows the new one at once, and so do comments, the breakdown and agents’ reads. Nothing in the documents is rewritten.

Seals are the exception: a seal is a snapshot, so it keeps the name each person had when it was sealed.

Deleting a user

DELETE /v1/users/{id} removes a user from your platform.

Documents they wrote in keep their last name, without the picture, so what they wrote stays credited.
Documents they owned pass to their other members with the highest role; one with no other member, and nobody else who wrote in it, is deleted, with its seals.
Their agents are revoked at once.
Their security keys and check-in history go with them.

Their external_id is free again afterwards. Sending it to PUT /v1/users/external/{external_id} creates a new person with a new Proof id: nothing from before comes back.

Merging users

Some products let people write before they have an account, then sign up later. POST /v1/users/{id}/merge moves everything from one user to another:

their documents and memberships,
the credit for everything they wrote,
their security keys and check-ins, and their check-in interval unless the user they join has one,
their agents; one for a client the user they join already connected joins that agent.

The first user is deleted afterwards. See Anonymous users for the whole flow.