Utilisateurs
Créer, lister et gérer depuis votre propre serveur les personnes de votre compte qui se connectent à la console.
Les routes des utilisateurs permettent à votre serveur de gérer les personnes de votre compte qui se connectent à la console, sans que personne n’ait à l’ouvrir. Elles s’authentifient avec votre clé d’API, comme le reste de l’API, et ne voient jamais que les utilisateurs du compte auquel appartient cette clé.
Les routes
| Méthode | Chemin | Ce qu’elle fait |
|---|---|---|
POST | /users-cl | Créer un utilisateur et lui envoyer le lien pour choisir son mot de passe |
GET | /users-cl | Lister les utilisateurs de votre compte |
GET | /users-cl/{id} | Lire un utilisateur |
PATCH | /users-cl/{id} | Renommer un utilisateur, ou l’autoriser ou non à se connecter |
DELETE | /users-cl/{id} | Supprimer un utilisateur |
À quoi ressemble un utilisateur
{
"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"
}
| Champ | Ce que c’est |
|---|---|
id | Désigne l’utilisateur. C’est ce que vous passez aux routes ci-dessous. |
firstName, lastName | Le nom de l’utilisateur. |
email | L’adresse avec laquelle l’utilisateur se connecte. |
isActive | Si l’utilisateur peut se connecter. Un utilisateur désactivé garde son compte mais ne peut plus se connecter. |
lastConnection | La date et l’heure de la dernière connexion, ou null si l’utilisateur ne s’est jamais connecté. |
createdAt | La date et l’heure de création de l’utilisateur. |
Un utilisateur est rendu sans mot de passe et sans permissions. Le premier n’est connu que de l’utilisateur. Les secondes sont accordées par un administrateur de votre compte, dans la console : votre clé d’API n’en détient aucune et ne peut en donner aucune.
Créer un utilisateur
POST /users-cl
Authorization: Bearer <apiKey>
Content-Type: application/json
{
"firstName": "Camille",
"lastName": "Martin",
"email": "camille.martin@example.com"
}
| Champ | Type | Obligatoire | Remarques |
|---|---|---|---|
firstName | chaîne | oui | De 2 à 300 caractères. |
lastName | chaîne | oui | De 2 à 300 caractères. |
email | chaîne | oui | Une adresse valide, 300 caractères au plus. C’est l’identifiant de connexion de l’utilisateur. |
- Vous ne choisissez jamais de mot de passe, et n’en voyez jamais. Un lien pour le définir est envoyé à l’adresse ; l’utilisateur le choisit depuis ce lien. Le lien est valable 72 heures, après quoi l’utilisateur peut en demander un nouveau avec « Forgot password » sur la page de connexion.
- Le
201répond du compte, non du courrier. Le message part après la réponse ; s’il n’arrive jamais, le compte existe, et l’utilisateur l’ouvre avec « Forgot password » sur la page de connexion. - L’utilisateur est créé sans aucune permission. Un administrateur de votre compte les lui accorde dans la console.
- Un champ qui n’est pas listé est ignoré, non refusé. Un
passwordou despermissionsdans le corps ne changent rien : l’utilisateur est créé comme décrit ci-dessus. - L’adresse ne peut pas être modifiée ensuite. Pour la corriger, supprimez l’utilisateur et créez-le de nouveau.
- Une adresse est unique dans tout Saphere, sans tenir compte des majuscules.
Camille.Martin@example.cometcamille.martin@example.comsont la même adresse. Une adresse déjà utilisée donne un409.
Réponse
201 Created
{ "id": "3f1a2b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" }
Une requête qui échoue à la validation donne un 400, et l’erreur dit ce qui ne va pas. La route est limitée à 20 appels par minute et par clé d’API, comme la création d’un jeton d’accès.
Lister les utilisateurs
GET /users-cl?take=100&skip=0
Authorization: Bearer <apiKey>
| Paramètre | Type | Remarques |
|---|---|---|
take | entier | De 1 à 1000. 100 par défaut. |
skip | entier | Nombre d’utilisateurs à sauter avant le début de la sélection. 0 par défaut. |
Les utilisateurs sont listés par date de création, le plus ancien d’abord, si bien que les pages se suivent sans se chevaucher : un utilisateur créé pendant que vous parcourez la liste la rejoint par la fin. La réponse est un simple tableau, sans total : une page plus courte que take est la dernière.
Lire un utilisateur
GET /users-cl/{id}
Authorization: Bearer <apiKey>
Répond 200 OK avec l’utilisateur. Un identifiant qui n’existe pas et un identifiant d’un autre compte donnent le même 404 : personne ne peut sonder les utilisateurs des autres comptes. Un identifiant mal formé donne un 400.
Modifier un utilisateur
PATCH /users-cl/{id}
Authorization: Bearer <apiKey>
Content-Type: application/json
{ "isActive": false }
| Champ | Type | Remarques |
|---|---|---|
firstName | chaîne | De 2 à 300 caractères. |
lastName | chaîne | De 2 à 300 caractères. |
isActive | booléen | false empêche l’utilisateur de se connecter ; true le lui permet de nouveau. |
Seuls les champs que vous envoyez changent, et email n’en fait pas partie : un email ou des permissions dans le corps sont ignorés, non refusés. La réponse est un 200 OK avec l’utilisateur tel qu’il est désormais.
Supprimer un utilisateur
DELETE /users-cl/{id}
Authorization: Bearer <apiKey>
200 OK en cas de succès, avec un corps vide. L’utilisateur ne peut plus se connecter.
Un utilisateur qui a écrit dans un ticket d’assistance ne peut pas être supprimé — la réponse est un 409 : désactivez-le plutôt, avec PATCH.
Un utilisateur qui détient des permissions est hors de portée
PATCH et DELETE n’agissent que sur les utilisateurs qui ne détiennent aucune permission — typiquement ceux que vous avez créés, tant qu’un administrateur de votre compte ne leur en a pas accordé. Sur tout autre, elles répondent 403 et ne changent rien. Votre clé ne détient aucune permission, elle ne peut donc pas toucher quelqu’un qui en détient.Exemple complet
Les commandes ci-dessous visent la Production. Les mêmes appels sur Test ne diffèrent que par l’adresse.
| Environnement | Base de l'API |
|---|---|
| Production | https://api.saphere.ai |
| Test | https://api.test.saphere.ai |
Une clé émise sur un environnement n’est jamais valable sur l’autre, et les utilisateurs n’existent pas sur les deux. Voir Environnements.
# Créer un utilisateur : le lien pour choisir son mot de passe part à l'adresse
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" }'
# Lister les cent premiers utilisateurs de votre compte
curl -s "https://api.saphere.ai/users-cl?take=100" \
-H "Authorization: Bearer $SAPHERE_API_KEY"
# Empêcher un utilisateur de se connecter
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 }'