5.2 Users, password hashes, and roles

Users aren't a special store — they're records in a dataset (default users) that the auth service reads through the data capability. That means you create and manage users with the same store contract you already know (Part 4).

A user record

Keyed by email, in the users dataset:

{ "passwordHash": "$argon2id$v=19$...", "roles": "A U", "kind": "user" }

• passwordHash — an argon2id hash for new users. Legacy bcrypt ($2…) hashes are also verified, so you can migrate users without forcing an immediate reset; new hashes are argon2id.
• roles — a space-separated string (or array) of role names. There's no fixed vocabulary — you choose the names (A for admin, U for user, E for editor, whatever your access rules reference).
• kind — "user" or "agent" (an agent principal is a non-human caller; the distinction surfaces on the agent surface and in logs).

Seeding a user

You write a user the same way you write any record — PUT into the dataset with a pre-computed hash:

PUT /data/users/ada@example.com
{ "passwordHash": "$argon2id$…", "roles": "A U", "kind": "user" }

Generate the argon2id hash with any standard argon2 tool, use rs2 auth create-admin, or hash inside a provisioning pipeline with $hashPassword (7.6). The server can also seed the first operator from bootstrapAdmin (10.7); after that, user lifecycle is your application policy.

Protect the users dataset. Because users are just records, the dataset that holds them must be guarded like any sensitive store — restrict write access (and usually read) with a role spec (5.4). You don't want the users mount world-writable.

Where the user dataset lives

By default auth looks in the users dataset of the tenant's data store; auth.userDataset changes the name. The dataset is a normal data container, so listing users, resetting a hash, or assigning roles are all ordinary store operations — subject, of course, to whatever access you put on that mount.

Roles are just strings you reference

Roles have no meaning on their own — they gain meaning when a mount's access spec references them (5.4). A user with "roles": "A U" can satisfy any rule that asks for A or U. Design your role names around the access rules you'll write, not the other way around.

Next: how those roles travel — tokens, cookies, and bearer headers.

← Previous: 5.1 The auth service · Manual home · Next: 5.3 Tokens, cookies, bearer headers →