Authentification

L'accès à l'API Scribee est sécurisé par le protocole OAuth 2.0.

Grant type

Le grant type utilisé est Client Credentials (client_id + client_secret). Il n'y a pas d'utilisateur intermédiaire : le client s'authentifie directement auprès de l'API pour obtenir un access token.

Obtenir un access token

Envoyez une requête POST sur l'endpoint /oauth/token avec vos identifiants et les scopes souhaités :

curl -X POST https://app.scribee.tech/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope="read write"

La réponse contient l'access token à utiliser dans l'en-tête Authorization de chaque requête :

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "read write",
  "created_at": 1767225600
}

created_at est un horodatage Unix en secondes. Traitez la réponse comme extensible : ne rejetez pas un champ que vous ne connaissez pas.

Scopes

Un access token donne accès à tous les workspaces accordés à votre application - GET /api/v1/workspaces les liste - et porte un ou plusieurs des scopes suivants :

Scope	Description
read	Requis sur les endpoints GET. Scope par défaut : ce qu'obtient une demande de token qui omet scope, à condition que votre application porte read.
write	Requis sur les endpoints POST, PATCH et PUT. Accepté aussi sur DELETE.
destroy	Alternative de moindre privilège à write sur les seuls endpoints DELETE, qui acceptent l'un ou l'autre.

Les scopes attachés à votre application sont fixés à sa création. Un responsable ou le propriétaire du workspace crée l'application lui-même depuis l'interface Scribee, dans Espace de travail > onglet API, section Applications OAuth. Le formulaire propose trois combinaisons cumulatives : read pour un client qui ne fait que consulter, read write pour un client qui crée et modifie, et read write destroy pour un client qui supprime également - read est toujours inclus. Le nom et les scopes restent modifiables ensuite depuis le même onglet, où l'application peut aussi être supprimée. Réduire les scopes révoque immédiatement les access tokens qui portaient les droits retirés ; les élargir, ou renommer l'application, ne révoque rien. Un token qui échapperait à cette révocation est de toute façon refusé - et révoqué - dès l'appel suivant : à partir du moment où ses scopes ne sont plus un sous-ensemble de ceux de l'application, il reçoit un 401 invalid_token. Après un changement de scopes, redemandez un token.

L'identifiant client reste consultable à tout moment sur la page de l'application, dans le même onglet API. Le secret client, lui, n'est affiché qu'une seule fois, à la création puis à nouveau à chaque régénération : il est conservé haché et n'est plus consultable ensuite. Le même onglet permet de le régénérer. La régénération invalide immédiatement l'ancien secret et révoque les access tokens encore actifs de l'application : déployez le nouveau secret avant votre prochain appel, sinon vos requêtes échouent avec les identifiants et les tokens qu'elles portaient jusque-là.

Une application peut aussi être provisionnée par un administrateur Scribee - c'est notamment le cas d'une application partagée entre plusieurs workspaces. Elle apparaît alors dans la liste du workspace avec la mention "Fournie par Scribee", en lecture seule : son nom, ses scopes et son secret ne se gèrent que du côté de Scribee. Le formulaire d'administration propose deux combinaisons, read et read write. destroy est un scope configuré à part entière - le serveur l'accepte sur une application et les endpoints DELETE l'honorent - mais si vous voulez un client qui supprime sans pouvoir écrire, demandez-le explicitement.

La valeur envoyée dans scope n'a pas à reprendre l'intégralité de ce qui vous a été accordé : tout sous-ensemble est accepté. invalid_scope n'est renvoyé que si vous demandez un scope situé hors de votre périmètre.

Omettre scope ne revient PAS toujours à demander read. Le serveur croise les scopes de votre application avec le scope par défaut read, et c'est ce croisement qu'il délivre : une application qui porte read reçoit read. Une application qui ne le porte pas croise à vide, et la demande de token est refusée avec invalid_scope - aucun token n'est émis, pas même un token sans scope. Une application destroy seul doit donc envoyer scope=destroy explicitement. Envoyez toujours le scope que vous voulez plutôt que de compter sur le défaut.

:::caution Ce que le serveur vérifie réellement, endpoint par endpoint

Les écritures sont contrôlées par scope : POST, PATCH et PUT exigent write, et DELETE exige destroy ou write. Un token read seul y reçoit un 403, avec le message Vous n'êtes pas autorisé à effectuer cette action.

Les lectures le sont également : un GET exige read. Un token dont les scopes omettent read reçoit un 403 sur un endpoint de lecture, avec le même message - un token qui ne porte que write ne lit pas, et un token qui ne porte que destroy ne lit pas davantage.

Demandez donc read dans toutes vos demandes de token dès que votre intégration lit quoi que ce soit, et read write dès qu'elle écrit. C'est ce que déclare la référence OpenAPI, et c'est ce que le serveur applique.

:::

GET /api/v1/health est la seule exception à l'authentification : il ne demande aucun token, précisément pour rester interrogeable quand vos identifiants sont en cause.

Filtrage par adresse IP

L'accès à l'API scoped à un tenant est également filtré par l'IPv4 allowlist du tenant cible, quand elle est configurée. Une requête provenant d'une IP refusée reçoit une réponse JSON 403 lors de la résolution directe du tenant, et les tenants refusés sont exclus des recherches de workspace et de ressources.

:::caution L'allowlist est strictement IPv4 Dès qu'un workspace a au moins une entrée dans son allowlist, une requête dont l'adresse source n'est pas une IPv4 est refusée, quelle que soit la liste - il n'existe aucune entrée qui autorise une adresse IPv6. Si vos serveurs sortent en dual-stack, forcez l'IPv4 vers app.scribee.tech avant de demander l'activation d'une allowlist, sinon vos appels basculeront en 403 de façon intermittente selon l'adresse utilisée. :::