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éthodeCheminCe qu’elle fait
POST/users-clCréer un utilisateur et lui envoyer le lien pour choisir son mot de passe
GET/users-clLister 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"
}
ChampCe que c’est
idDésigne l’utilisateur. C’est ce que vous passez aux routes ci-dessous.
firstName, lastNameLe nom de l’utilisateur.
emailL’adresse avec laquelle l’utilisateur se connecte.
isActiveSi l’utilisateur peut se connecter. Un utilisateur désactivé garde son compte mais ne peut plus se connecter.
lastConnectionLa date et l’heure de la dernière connexion, ou null si l’utilisateur ne s’est jamais connecté.
createdAtLa 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"
}
ChampTypeObligatoireRemarques
firstNamechaîneouiDe 2 à 300 caractères.
lastNamechaîneouiDe 2 à 300 caractères.
emailchaîneouiUne 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 201 ré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 password ou des permissions dans 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.com et camille.martin@example.com sont la même adresse. Une adresse déjà utilisée donne un 409.

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ètreTypeRemarques
takeentierDe 1 à 1000. 100 par défaut.
skipentierNombre 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 }
ChampTypeRemarques
firstNamechaîneDe 2 à 300 caractères.
lastNamechaîneDe 2 à 300 caractères.
isActivebooléenfalse 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.

EnvironnementBase de l'API
Productionhttps://api.saphere.ai
Testhttps://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 }'