Oslaw API publique1.0.0

Authentification

Chaque requête exige un token dans l’en-tête Authorization: Bearer <token>. Il y a deux façons d’en obtenir un, et le choix dépend de qui appelle :

Clé d’API · le cabinet qui automatise son propre compte

Créez la clé dans Paramètres › Intégrations. Vous y cochez ses droits, exactement comme pour un rôle, et le secret s’affiche une seule fois. Il n’y a rien d’autre à faire :

curl https://api.oslaw.legal/v1/me \
  -H "Authorization: Bearer osk_live_VOTRE_CLE"

Quatre points à connaître avant d’en créer une :

• ses droits sont bornés à ceux de la personne qui les règle : un droit qu’elle n’a pas ne se coche pas. Ils se modifient ensuite dans l’écran, sans changer le secret ni couper l’outil ;
• elle atteint les dossiers ouverts, et ceux où vous l’invitez. Les dossiers restreints ne lui sont ouverts que si le propriétaire du cabinet choisit de l’y inscrire ;
• toute écriture faite par une clé entre au journal d’audit du cabinet ;
• le secret ne se relit pas. Pour le remplacer : créez la nouvelle clé, basculez votre outil dessus, révoquez l’ancienne. Aucune coupure.

Révoquer une clé la ferme immédiatement, y compris pour un appel déjà en cours de session.

OAuth 2.1 · une application tierce au nom d’un cabinet

Attention : le client secret d’un « Accès API » n’est pas un token. C’est l’identité d’une application ; il sert à obtenir un access token, pas à s’authentifier directement.

Obtenir un access token

Créez d’abord un « Accès API » dans Paramètres › Intégrations → vous obtenez un client_id et un client_secret (affiché une seule fois). Ensuite, deux cas :

• Vous utilisez un outil (Make, Zapier, Postman, une bibliothèque OAuth) : il réalise tout le flux pour vous (voir « Connecter un outil » ci-dessous). C’est le cas le plus courant.
• Vous codez l’intégration vous-même : suivez les 3 étapes concrètes ci-dessous (endpoints sur le domaine de cette API).

Étape 1 : envoyez le membre sur la page d’autorisation. Ouvrez cette URL dans son navigateur (l’écran de consentement Oslaw s’affiche, il approuve) :

GET /oauth/authorize
      ?response_type=code
      &client_id=VOTRE_CLIENT_ID
      &redirect_uri=UNE_DE_VOS_REDIRECT_URIS
      &code_challenge=BASE64URL(SHA256(code_verifier))
      &code_challenge_method=S256
      &state=CHAINE_ALEATOIRE

Étape 2 : récupérez le code. Oslaw renvoie le navigateur vers votre redirect_uri avec ?code=...&state=.... Vérifiez que state est bien celui que vous aviez envoyé (anti-CSRF).

Étape 3 : échangez le code contre un token (appel serveur à serveur) :

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=LE_CODE_RECU
&redirect_uri=LA_MEME_REDIRECT_URI
&client_id=VOTRE_CLIENT_ID
&client_secret=VOTRE_CLIENT_SECRET
&code_verifier=LE_CODE_VERIFIER

Réponse : { "access_token": "…", "refresh_token": "…", "expires_in": … }. Utilisez access_token en Authorization: Bearer. À l’expiration, rejouez POST /oauth/token avec grant_type=refresh_token&refresh_token=….

Connecter un outil (Make, Zapier, Postman…)

Ces outils gèrent le flux OAuth 2.1 pour vous ; il suffit de les configurer :

1. Dans l’outil, créez une connexion OAuth 2.0 Authorization Code ; il vous affiche une Redirect URI (l’adresse où il veut recevoir le code).
2. Copiez cette Redirect URI dans les redirect_uris de votre « Accès API » (Oslaw). C’est l’étape indispensable : sans elle déclarée, l’autorisation est refusée.
3. Renseignez dans l’outil : Authorize URI = /oauth/authorize et Token URI = /oauth/token (sur le domaine de cette API), votre client_id et client_secret. Le scope peut rester vide (le périmètre réel = les droits du membre).
4. Lancez l’autorisation → un membre approuve sur l’écran de consentement Oslaw → l’outil obtient l’access_token (et le rafraîchit automatiquement).
5. Appelez ensuite les endpoints ci-dessous (/v1/...) ; l’outil attache le Authorization: Bearer tout seul.

Droits & périmètre

Les deux voies aboutissent au même endroit : un appel n’obtient jamais plus que les droits du principal qui le porte, et les données restent cloisonnées à un seul cabinet.

• Clé d’API : la clé porte ses propres droits, choisis à sa création et bornés à ceux de la personne qui l’a créée. Pour restreindre une automatisation, cochez moins de droits sur la clé.
• OAuth 2.1 : le token agit au nom du membre qui l’a autorisé et n’obtient que ses droits. Il n’y a pas de scope propre au token : pour limiter une application tierce, faites-la autoriser par un membre au rôle restreint.

Limite de débit

L’API accepte 100 requêtes par minute et par adresse IP appelante. Au-delà, elle répond 429 Too Many Requests : espacez les appels et réessayez. Le compteur porte sur l’adresse IP, pas sur la clé : plusieurs clés appelant depuis le même serveur partagent le même budget.

Pour un traitement en masse, préférez la pagination des endpoints de liste à des appels unitaires en rafale.

Tester ici

Cliquez Authorize et collez soit une clé d’API, soit l’access_token d’une session valide, puis dépliez une opération et Try it out.