Users
Creating, listing and managing the people of your account who sign in to the console — from your own server.
The users routes let your server manage the people of your account who sign in to the console, without anyone opening it. They are authenticated with your API key, like the rest of the API, and they only ever see the users of the account that key belongs to.
The routes
| Method | Path | What it does |
|---|---|---|
POST | /users-cl | Create a user and send them the link to choose a password |
GET | /users-cl | List the users of your account |
GET | /users-cl/{id} | Read one user |
PATCH | /users-cl/{id} | Rename a user, or let them sign in or not |
DELETE | /users-cl/{id} | Delete a user |
What a user looks like
{
"id": "3f1a2b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
"firstName": "Camille",
"lastName": "Martin",
"email": "camille.martin@example.com",
"isActive": true,
"lastConnection": null,
"createdAt": "2026-11-09T09:00:00.000Z"
}
| Field | What it is |
|---|---|
id | Names the user. It is what you pass to the routes below. |
firstName, lastName | The user’s name. |
email | The address the user signs in with. |
isActive | Whether the user can sign in. A deactivated user keeps their account but cannot connect. |
lastConnection | The date and time of the last sign-in, or null if the user never signed in. |
createdAt | The date and time at which the user was created. |
A user is returned without a password and without permissions. The first is never known to anyone but the user. The second are granted by an administrator of your account, in the console: your API key holds none and cannot give any.
Create a user
POST /users-cl
Authorization: Bearer <apiKey>
Content-Type: application/json
{
"firstName": "Camille",
"lastName": "Martin",
"email": "camille.martin@example.com"
}
| Field | Type | Required | Notes |
|---|---|---|---|
firstName | string | yes | From 2 to 300 characters. |
lastName | string | yes | From 2 to 300 characters. |
email | string | yes | A valid address, up to 300 characters. It is the user’s login. |
- You never choose a password, and never see one. A link to define it is sent to the address; the user sets it from there. The link is valid for 72 hours, after which the user can ask for a new one with “Forgot password” on the sign-in page.
- The
201answers for the account, not for the e-mail. The message is sent after the response; if it never arrives, the account exists, and the user opens it with “Forgot password” on the sign-in page. - The user is created without any permission. An administrator of your account grants them in the console.
- A field that is not listed is ignored, not refused. A
passwordorpermissionsin the body changes nothing: the user is created as described above. - The address cannot be changed afterwards. To correct it, delete the user and create them again.
- An address is unique across Saphere, capitals aside.
Camille.Martin@example.comandcamille.martin@example.comare the same address. One that is already used answers409.
Response
201 Created
{ "id": "3f1a2b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" }
A request that fails validation answers 400, and the error lists what. The route is limited to 20 calls per minute per API key, like creating an access token.
List the users
GET /users-cl?take=100&skip=0
Authorization: Bearer <apiKey>
| Parameter | Type | Notes |
|---|---|---|
take | integer | From 1 to 1000. Defaults to 100. |
skip | integer | Users to skip before the selection starts. Defaults to 0. |
Users are listed by creation date, oldest first, so pages follow one another without overlapping: a user created while you go through the list joins the end. The answer is a plain array, with no total: a page shorter than take is the last one.
Read a user
GET /users-cl/{id}
Authorization: Bearer <apiKey>
Answers 200 OK with the user. An id that does not exist and an id that belongs to another account answer the same 404: nobody can probe for users of other accounts. A malformed id answers 400.
Update a user
PATCH /users-cl/{id}
Authorization: Bearer <apiKey>
Content-Type: application/json
{ "isActive": false }
| Field | Type | Notes |
|---|---|---|
firstName | string | From 2 to 300 characters. |
lastName | string | From 2 to 300 characters. |
isActive | boolean | false stops the user from signing in; true lets them again. |
Only the fields you send change, and email is not one of them: an email or permissions in the body is ignored, not refused. The answer is 200 OK with the user as it now stands.
Delete a user
DELETE /users-cl/{id}
Authorization: Bearer <apiKey>
200 OK on success, with an empty body. The user can no longer sign in.
A user who has written in a support ticket cannot be deleted — the answer is 409: deactivate them instead, with PATCH.
A user who holds permissions is out of reach
PATCH and DELETE act only on users who hold no permission — typically the ones you created, until an administrator of your account grants them one. On any other user they answer 403, and change nothing. Your key holds no permission of its own, so it cannot touch someone who holds some.Worked example
The commands below run against Production. The same calls on Test differ only in the address.
| Environment | API base |
|---|---|
| Production | https://api.saphere.ai |
| Test | https://api.test.saphere.ai |
A key issued for one environment is never valid on the other, and users do not exist on both. See Environments.
# Create a user: the link to choose a password goes to the address
curl -sX POST https://api.saphere.ai/users-cl \
-H "Authorization: Bearer $SAPHERE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "firstName": "Camille", "lastName": "Martin", "email": "camille.martin@example.com" }'
# List the first hundred users of your account
curl -s "https://api.saphere.ai/users-cl?take=100" \
-H "Authorization: Bearer $SAPHERE_API_KEY"
# Stop a user from signing in
curl -sX PATCH https://api.saphere.ai/users-cl/3f1a2b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b \
-H "Authorization: Bearer $SAPHERE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'