Aller au contenu principal

Authentification

L'API Batis Integration utilise OAuth2 avec le flow client_credentials.

Les identifiants client_id et client_secret sont fournis par Batis pour un environnement donné. Ils permettent d'obtenir un access_token court, associé à un périmètre d'accès.

Obtenir un token​

curl "https://integration.batis.io/api/v1/oauth/token" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=integration:read"

Réponse :

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "integration:read"
}

Le token est valable 3 600 secondes. Aucun refresh token n’est émis : refaire cet échange à l’expiration. Le paramètre scope est facultatif ; s’il est absent ou vide, les scopes autorisés du client sont utilisés. Cette version propose integration:read. Les identifiants sont acceptés uniquement en HTTP Basic. La réponse de token comporte Cache-Control: no-store et Pragma: no-cache.

Appeler l'API​

curl https://integration.batis.io/api/v1/operation \
  -H "Authorization: Bearer ACCESS_TOKEN"

Erreurs courantes​

  • 400 Bad Request : grant_type non supporté ou scope demandé non autorisé.
  • 401 Unauthorized : identifiants client absents, invalides, révoqués ou token invalide.
  • 403 Forbidden : token valide, mais accès refusé à la ressource demandée.
  • 429 Too Many Requests : trop d'appels dans une période courte.

Format des erreurs OAuth​

Les erreurs OAuth du token et des ressources utilisent le même format. Exemple pour /oauth/token :

{
  "error": "invalid_client",
  "error_description": "Client credentials are invalid."
}
  • invalid_request (400) : formulaire invalide, grant_type absent, paramètres répétés ou identifiants fournis dans le corps.
  • unsupported_grant_type (400) : seul client_credentials est pris en charge.
  • invalid_scope (400) : scope invalide ou non autorisé.
  • invalid_client (401) : identifiants absents, malformés, invalides ou révoqués ; le header WWW-Authenticate indique Basic.
  • rate_limit_exceeded (429) : limite atteinte ; respecter le délai Retry-After, exprimé en secondes.

Sur les ressources, un token invalide ou expiré donne 401, et un token valide sans le scope integration:read donne 403 avec insufficient_scope. Ces réponses comportent un challenge Bearer et le même corps OAuth avec error et error_description. Le statut est porté par la réponse HTTP. Les erreurs de validation ou métier conservent le format d’erreur habituel de l’API.

Limites et révocation​

Pour dimensionner votre intégration, prévoyez au plus 30 demandes de token par minute et par IP, et 600 appels aux ressources par minute et par client, tous endpoints de ressources confondus. Réutilisez le token pendant sa durée de validité. En cas de réponse 429, respectez le délai indiqué par Retry-After avant de réessayer.

Un client est rattaché à une équipe Batis. Batis peut le révoquer : cette révocation bloque immédiatement ses tokens déjà émis et les nouvelles demandes de token.