Aperçu de l'API REST ClearPolicy

L’API REST ClearPolicy vous donne un accès programmatique aux personnes, groupes, documents et demandes de validation de votre organisation. Tous les points de terminaison communiquent via HTTPS et renvoient du JSON.

URL de base

https://api.clearpolicy.app/api/v1

Le préfixe du chemin de l’API (/api/v1) est inclus dans chaque URL de requête. La version actuelle et unique est v1.

Authentification

Tous les points de terminaison nécessitent un jeton porteur API valide. Passez le jeton dans l’en-tête Authorization :

Authorization: Bearer YOUR_ACCESS_TOKEN

Consultez Authentification pour les instructions sur la création d’un jeton.

Votre organisation doit disposer d’un abonnement actif ou se trouver dans sa période d’essai. Si votre essai a expiré ou si votre abonnement est inactif, toutes les requêtes API renvoient une réponse 402 Payment Required.

Accès par rôle

L’accès à l’API suit votre rôle dans ClearPolicy. Les propriétaires et administrateurs d’organisation peuvent créer des jetons API et utiliser les points de terminaison des personnes, groupes, documents et demandes de validation. Les jetons liés à des gestionnaires de groupe peuvent utiliser GET /me pour confirmer le jeton et l’organisation, mais les autres points de terminaison de l’API REST renvoient 403 Forbidden.

Format des réponses

Toutes les réponses sont au format JSON. Les réponses réussies renvoient la ressource ou la collection demandée directement dans le corps de la réponse.

Identifiants

Tous les identifiants de ressources sont des ULID — des identifiants en chaîne triables lexicographiquement. Ils sont représentés sous forme de chaînes en minuscules, par exemple :

01kg82xqfx6fvr046d15hnfmjv

Pagination

Les points de terminaison de liste renvoient des résultats paginés. La réponse comprend un tableau data ainsi que des objets links et meta :

{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}

Utilisez les paramètres de requête page et per_page pour naviguer dans les résultats. per_page accepte des valeurs comprises entre 1 et 100, la valeur par défaut étant 25.

Erreurs

Les erreurs renvoient du JSON avec un champ error décrivant le problème :

{
  "error": "Person not found."
}

Codes de statut HTTP courants :

Statut	Signification
`200 OK`	Requête réussie.
`201 Created`	Ressource créée avec succès.
`400 Bad Request`	La requête était invalide (par ex. document non publié).
`401 Unauthorized`	Jeton d’accès manquant ou invalide.
`402 Payment Required`	L’essai de votre organisation a expiré ou l’abonnement est inactif. Consultez votre page de facturation pour vous abonner.
`403 Forbidden`	Le jeton ne dispose pas des autorisations requises.
`404 Not Found`	La ressource demandée n’existe pas dans votre organisation.
`422 Unprocessable Entity`	Échec de la validation — vérifiez les paramètres de la requête.
`429 Too Many Requests`	Limite de débit dépassée — attendez et réessayez.

Limitation de débit

Chaque jeton d’API est limité à 60 requêtes par minute. Les limites s’appliquent par jeton, et non par organisation — plusieurs jetons ont chacun leur propre quota. Si vous dépassez la limite, l’API renvoie 429 Too Many Requests. Les réponses incluent les en-têtes Retry-After et X-RateLimit-* pour indiquer quand réessayer. Utilisez un backoff exponentiel lors des tentatives.

Aperçu

Me

Personnes

Documents

Groupes

Demandes de validation

Aperçu de l'API REST ClearPolicy

URL de base

Authentification

Accès par rôle

Format des réponses

Identifiants

Erreurs

Limitation de débit

​URL de base

​Authentification

​Accès par rôle

​Format des réponses

​Identifiants

​Pagination

​Erreurs

​Limitation de débit

URL de base

Authentification

Accès par rôle

Format des réponses

Identifiants

Pagination

Erreurs

Limitation de débit