API REST : authentification

Chaque requête à l’API REST de Personyze doit être authentifiée avec une clé API, transmise en HTTPS. Il n’existe aucun endpoint public ou non authentifié.

Si vous ne l’avez pas encore lu, commencez par la présentation et le démarrage rapide de l’API REST pour la forme générale de chaque requête.

Où trouver votre clé API

Dans l’interface d’administration de Personyze, allez dans Paramètres → Intégrations → API. Chaque compte Personyze auquel vous avez accès a sa propre clé — elles ne sont pas interchangeables.

Comment envoyer la clé

Utilisez l’authentification HTTP Basic avec le nom d’utilisateur api et la clé comme mot de passe. Deux façons courantes de procéder :

Raccourci curl — identifiants dans l’URL

Pratique pour les tests ponctuels et les scripts shell :

curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'

En-tête Authorization — à privilégier pour le code en production

La plupart des bibliothèques clientes HTTP n’analysent pas de façon fiable user:pass@host dans les URL, et placer des identifiants dans l’URL les expose dans les journaux du serveur web et l’historique du navigateur. Pour le code en production, construisez explicitement l’en-tête Authorization :

Authorization: Basic <base64("api:" + API_KEY)>

Curl avec un en-tête explicite

curl https://app.personyze.com/rest/users/where/internal_id=42 \
     -H "Authorization: Basic $(printf 'api:%s' YOUR_API_KEY | base64)"

Python (avec requests)

import requests

r = requests.get(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    auth=('api', YOUR_API_KEY),
)
r.raise_for_status()
data = r.json()

JavaScript (avec fetch)

const r = await fetch(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    { headers: { Authorization: 'Basic ' + btoa('api:' + API_KEY) } }
);
const data = await r.json();

Codes d’erreur d’authentification

Accès multi-comptes / multi-locataires

La clé API détermine sur quel compte Personyze porte la requête. L’URL de l’endpoint ne nomme jamais le compte — il est déduit de la clé. Pour travailler sur plusieurs comptes depuis le même client, conservez une clé par compte et choisissez la bonne avant chaque requête.

Les ID d’objets sont eux aussi propres à chaque compte : l’action 42 du compte A n’a aucun rapport avec l’action 42 du compte B. Si votre code stocke des ID Personyze à côté de vos propres données, stockez aussi l’ID du compte (ou au moins la clé API qui les a créés), afin de pouvoir plus tard renvoyer les requêtes vers le bon compte.

Limitation du débit et délais d’expiration

• Les requêtes rapides du traqueur / SDK disposent d’un budget de 10 secondes d’exécution. Les requêtes plus longues sont déconnectées de force avec une erreur de type 503. La plupart des appels à l’API REST ne passent pas par ce chemin rapide, mais sachez que les requêtes complexes sur de grandes tables peuvent nécessiter une indexation soignée pour rester sous la limite.
• POST /rest/users est limité par compte : au plus une insertion en cours à la fois. Au-delà d’une attente d’une seconde dans la file, les requêtes sont rejetées avec 400 Too many simultaneous requests. Réessayez avec un délai exponentiel. (C’est détaillé sur la page de l’objet users.)
• Les autres endpoints ne sont pas limités au niveau de l’application pour l’instant — mais considérez l’API comme une ressource partagée et évitez de la marteler depuis de nombreux processus parallèles quand des appels séquentiels suffiraient.

Étapes suivantes