How-to guide
Invite users and set roles
Invite staff by one-time token, change a role, switch an account off and issue a password reset link as an admin.
This guide shows how to add people to your organization and manage their access. You need an admin account. Staff roles are reviewer and admin. See Roles for what each one can do.
1. Invite a person#
Send POST /api/v1/users/invites/ with an email address and a role.
curl -X POST https://API/api/v1/users/invites/ \
-H "Content-Type: application/json" -H "X-CSRFToken: $CSRF" -H "Referer: https://API/" -b jar \
-d '{"email":"rima@example.test","role":"reviewer"}'{"id":"3f5f843b-b7a0-4bec-abbc-818ea2ea0665","email":"rima@example.test","role":"reviewer","state":"open","expires_at":"2026-11-22T00:48:21+03:00","token":"xYzW7Z9m..."}The token is shown once. Only a hash is stored. If your deployment has email set up, Yaqeen also sends the invitation by email. Otherwise, give the token to the person yourself. The token works once and ends after 7 days.
2. The person accepts#
The person does not sign in. They send the token with the username and password they choose. No admin sees the password.
curl -X POST https://API/api/v1/auth/invite/accept/ \
-H "Content-Type: application/json" \
-d '{"token":"xYzW7Z9m...","username":"rima","password":"YOUR-OWN-PASSWORD"}'The answer is 201 with {"username":"rima","role":"reviewer"}. The password needs at least 12 characters and cannot be a common password or only digits.
3. Check and cancel invitations#
GET /api/v1/users/invites/lists invitations. Thestateisopen,accepted,cancelledorexpired. After a person accepts, the email address is removed from the record.- Each row also has
created_atandinvited_by, the username of the admin who made it. POST /api/v1/users/invites/{id}/revoke/cancels an open invitation.POST /api/v1/users/invites/{id}/resend/replaces an open or expired invitation with a new one for the same address and role. The old link stops working. The answer has the newtoken, shown once. A cancelled or used invitation answers409 closed.
All of this is in the dashboard under Settings, People, where an admin also changes roles, switches accounts off and on, and makes reset links. A change that needs a second admin shows a notice and stays unchanged until that admin approves it.
GET /api/v1/users/lists accounts. You can filter withrole,is_activeandq(part of a username).
4. Change a role or switch an account off#
Find the account id in GET /api/v1/users/. Then send PATCH /api/v1/users/{id}/:
{ "role": "reviewer" }or
{ "is_active": false }Accounts are switched off, never deleted. These rules apply:
- You cannot change your own role or switch yourself off (
409 own_account). - The last active admin cannot be removed (
409 last_admin). Make another admin first. - A merchant stays a merchant (
400 invalid_role). - An account change needs a second person by default. If another admin is active, the answer is
202with"status": "pending_approval". That admin decides it as in Approve a change as the second person. If you are the only active admin, the change runs at once.
5. Help someone who forgot their password#
Send POST /api/v1/users/{id}/reset-link/. You get a token and an end time:
{"token":"6yu5nv8m...","expires_at":"2026-11-14T22:48:33Z"}Give the token to the person. The token is shown once, works once and ends after 60 minutes. A new link ends any older one for the same person. The person sets a new password without signing in:
curl -X POST https://API/api/v1/auth/password/reset/ \
-H "Content-Type: application/json" \
-d '{"token":"6yu5nv8m...","password":"YOUR-NEW-PASSWORD"}'The answer is 204 with no body. A password that is too weak answers 400 invalid and the link stays valid. A link that was used, ended or replaced answers 400 invalid_link. Issue a new one.
A reset link is better than POST /api/v1/users/{id}/password/, where you type the new password and so you know it.
Approve a sign-up#
Anyone can ask for access, with a Google account or with a username and password. Either way the API creates an account that is switched off, with the role reviewer, and tells the person it is waiting for approval.
- Send
GET /api/v1/users/?is_active=false.- A sign-up from Google has
"login_method": "google"and the person's address inemail. The address is confirmed by Google, and it is the username. - A sign-up with a password has
"login_method": "password", theemailthe person typed. The email is not confirmed, so treat it as a claim. Anyone can type any address.
- A sign-up from Google has
- Check that you know the person. Then send
PATCH /api/v1/users/{id}/with{"is_active": true}. Include"role"(revieweroradmin) in the same request. For a person who has never signed in, a request without a role answers400 role_required. - Tell the person. Then they can sign in. A Google sign-up uses the Google button, and a password sign-up uses the username and password they chose.
To refuse a request, leave the account switched off. Accounts are never deleted. If another admin is active, a change like this waits for that admin, as in step 4.
6. Add a store owner#
A merchant account belongs to one owner. Send POST /api/v1/users/merchants/ with username, password and owner_id, the id you used when you loaded the owner. The owner must already be loaded. To avoid knowing the merchant's password, set a long random one that you do not keep. Then issue a reset link as in step 5.
If it does not work#
409 already_invited: that address has an open invitation. Cancel it or wait for it to end.400 bad_emailor400 invalid_role: check the address. The role must berevieweroradmin.400 invalid_invite: the token was used, cancelled, ended or mistyped. Send a new invitation.409 username_taken: choose another username.400 bad_password: the password is too short or too common.
For more, see Troubleshooting.
Next steps#
- Approve a change as the second person: how a pending account change is decided.
- Roles: what each role can do and why.
- Roles and permissions: the full table.
- Set up your organization: where inviting people fits in the setup.