Authentification

Introduction

l’API Sage Business Cloud Comptabilité est sécurisée par une authentification Oauth 2.0.

OAuth, abréviation de « Open Authorization », est un protocole standard ouvert permettant une autorisation API sécurisée.

Afin d’éviter tout risque d’interception de ces données par des tiers et leur utilisation abusive, une autorisation des transferts de données effectués entre l’API Sage Business Cloud Comptabilité et l’application Sage Business Cloud Comptabilité est par conséquent nécessaire.

Vous n’êtes pas familiarisé avec le protocole Oauth ?
Nous avons trouvé que cet article sur OAuth 2.0, publié sur le site Zeste de savoir, aidait facilement à comprendre son intérêt et son utilisation.

Jeton d’accès (Acces Token)

A chaque sollicitation de l’API Sage Business Cloud Comptabilité, vous devez fournir un jeton d’accès (Access Token) valide dans l’en-tête d’autorisation (authorization header).

Authorization: Bearer {Access Token}

Un jeton d’accès appartient à un seul compte d’utilisateur dans Sage Business Cloud Comptabilité. Cela signifie qu’un utilisateur de votre application pourra accéder à toutes les données de ses sociétés (dossiers comptables) qui lui sont autorisées dans l’interface de Sage Business Cloud Comptabilité.
Dans Sage Business Cloud Comptabilité, un utilisateur peut en effet avoir accès à une ou plusieurs sociétés. il doit d’abord sélectionner la société pour pouvoir ensuite accéder aux données de cette société.

Droits (scopes)

Votre application devra aussi autoriser les droits nécessaires à son fonctionnement (scopes).
A l’exemple d’une app mobile qui vous demande des autorisations d’accès aux contacts, à la caméra, au micro, au téléphone, au stockage, etc, votre application devra autoriser l’accès aux seules ressources qui lui sont nécessaires.

Attention ! n’accordez que les droits nécessaires, par exemple si votre application ne prévoit pas d’écrire de données dans la comptabilité il n’est pas nécessaire de donner le droit Ecritures données comptables (EDC).

Obtenir un jeton d’accès (Obtain an Access Token)

Les étapes suivantes vous expliquent comment obtenir un jeton d’accès pour une application web et comment utiliser le rafraichissement d’un jeton (Refresh Token) pour obtenir un nouveau jeton si l’actuel a expiré.

1. Requête d’obtention d’un code d’autorisation (Authorization request)

Vous devez contacter le serveur d’autorisation de Sage Business Cloud Comptabilité en appelant l’url d’authentification avec la méthode GET et les paramètres requis :

GET

Auth URL

Paramètres	Valeur
`response_type`	Ce paramètre doit toujours contenir `code`
`state`	Une valeur de votre choix pour prévenir le cross-site request forgery
`client_id`	Le `Client ID` qui a été généré lors de la création de votre app depuis le parcours développeur.
`scope bêta`	Les autorisations nécessaires pour votre application séparées par un espace `%20` : `offline_access` `Company.Write.All` - Ecriture informations société `Company.Read.All` - Lecture informations société `Parameter.Write.All` - Ecriture paramètres société `Parameter.Read.All` - Lecture paramètres société `Account.Write.All` - Ecriture comptes généraux `Account.Read.All` - Lecture comptes généraux `Tiers.Write.All` - Ecriture tiers `Tiers.Read.All` - Lecture tiers `Tax.Write.All` - Ecriture taxes `Tax.Read.All` - Lecture taxes `Journal.Write.All` - Ecriture journaux `Journal.Read.All` - Lecture journaux `History.Accounting.Write.All` - Ecriture écritures comptables `History.Accounting.Read.All` - Lecture écritures comptables
`scope`	Les autorisations nécessaires pour votre application séparées par un espace `%20` : `openid` `offline_access` `LDC` - Lecture données comptables `EDC` - Ecriture données comptables
`redirect_uri`	L’url de redirection (`Callback URL`) que vous avez mentionnée dans votre app.

Remarque

La valeur offline-access mentionnée dans scope est nécessaire pour obtenir un jeton d’actualisation (Refresh Token)

Les erreurs possibles

access_denied : Sage Business Cloud Comptabilité refuse d’autoriser votre application.
invalid_request : Un paramètre requis est manquant, invalide ou fourni plusieurs fois.
invalid_scope : Les droits mentionnés dans scope sont incorrects ou insuffisants.
server_error : Le serveur d’autorisation rencontre une erreur inattendue qui l’empêche de répondre à la demande.
temporarily_unavailable : Le serveur d’autorisation n’est pas disponible. Nous vous recommandons d’attendre 10 minutes avant de réessayer.
unauthorized_client : Le client n’est pas autorisé à effectuer cette action. Cela peut être dû à une valeur client_id incorrecte.
unsupported_response_type : Le serveur d’autorisation ne prend pas en charge la méthode utilisée pour demander le code. Vous devez vous assurer que le type de réponse dans votre demande est code.

2. Renvoi du code d’autorisation pour obtenir le jeton d’accès

Si l’appel est correct, un code de réponse HTTP 302 Found est retourné et la réponse renvoie un champ d’entête (Response Headers) nommé location contenant :

l’url de redirection envoyée dans le GET,
un code d’autorisation attribué par le serveur d’authentification,
la valeur state envoyée dans le GET.

Response Headers

location: "{url de redirection}?code={code d'autorisation}&state={valeur state}"

Vous devez ensuite effectuer un appel POST pour obtenir le Token :

POST

Access Token URL beta

Access Token URL

Paramètres	Valeur
`grant_type`	Ce paramètre doit contenir `authorization_code`
`code`	Le code renvoyé par l’appel `GET` décrit précédemment.
`redirect_uri`	L’url de redirection (`Callback URL`) que vous avez mentionnée dans votre app
`client_id`	Le `Client ID` qui a été généré lors de la création de votre app
`client_secret`	Le `Client Secret` qui a été généré lors de la création de votre app

Si l’autorisation est accordée, la réponse renverra :

access_token : la valeur du jeton d’accès utilisée pour l’authentification de vos requêtes à l’API Sage Business Cloud Comptabilité
expire_in : la durée en secondes pendant laquelle le jeton d’accès est accordé,
token_type : contient toujours Bearer,
scope : les droits qui ont été réellement autorisés,
refresh_token: La valeur du jeton d’actualisation.

Remarques

Assurez-vous de ne pas partager ce jeton d’accès (Access Token) et de ne pas le stocker dans un emplacement dangereux.
Réservez jusqu’à 2048 octets dans votre stockage de données pour ce jeton d’accès (Access Token)
Réservez également jusqu’à 2048 octets dans votre stockage de données pour le jeton d’actualisation (Refresh Token).
Vous ne devez pas partager ce jeton d’actualisation ou le stocker à un endroit non sécurisé telle qu’une session de navigateur non chiffrée.

Les erreurs possibles

invalid_request : Un paramètre requis est manquant, invalide ou fourni plusieurs fois.
invalid_grant : le paramètre grant_type mentionné est invalide ou inconnu, ou le code d’autorisation pourrait être expiré (après 60 secondes), déjà utilisé ou inconnu, ou le jeton d’actualisation a expiré ou a été révoqué.
invalid_client : Le client ne peut pas être authentifié. Cela peut être dû à une valeur client_id ou client_secret incorrecte.
unauthorized_client : Le client n’est pas autorisé à utiliser le grant_type spécifié.
unsupported_grant_type : Le serveur d’autorisation ne prend pas en charge le grant_type spécifié. Vous devez vous assurer que le grant_type dans votre demande est authorization_code ou refresh_token.

Renouveler un jeton d’accès (renew a Refresh Token)

Vous pouvez utiliser le renouvellement d’un jeton d’accès pour obtenir un nouveau jeton d’accès si le jeton actuel a expiré. Cela signifie que vos utilisateurs ne sont pas tenus d’autoriser votre application chaque fois que vous demandez un nouveau jeton.

POST

Access Token URL beta

Access Token URL

Paramètres	Valeur
`grant_type`	Doit contenir `refresh_token`
`refresh_token`	Doit contenir la valeur de `refresh_token` renvoyée par la réponse d’obtention du jeton d’accès.
`client_id`	Le `Client ID` qui a été généré lors de la création de votre app
`client_secret`	Le `Client Secret` qui a été généré lors de la création de votre app

Si l’autorisation est accordée, la réponse renverra notamment :

access_token : la valeur du nouveau jeton d’accès
refresh_token : la valeur du nouveau jeton d’actualisation

Révoquer un jeton d’actualisation (revoke a Refresh Token)

Vous pouvez révoquer un jeton d’actualisation afin qu’il ne soit plus valide pour obtenir de nouveaux jetons d’accès.

Veuillez noter que vous ne pouvez pas révoquer les jetons d’accès, ils sont valables pendant toute leur durée de vie.

Une fois qu’un jeton d’actualisation est révoqué, il ne peut plus être utilisé pour obtenir un nouveau jeton d’accès, de sorte qu’à l’expiration du jeton d’accès courant, l’utilisateur devra de nouveau se connecter pour avoir accès à l’application.

POST

Access Token URL beta

Access Token URL

Paramètres	Valeur
`token`	La valeur du `refresh_token` que vous souhaitez révoquer
`client_id`	Le `Client ID` qui a été généré lors de la création de votre app
`client_secret`	Le `Client Secret` qui a été généré lors de la création de votre app

Si l’opération a réussi vous obtiendrez une réponse with HTTP status 200 :

{
  "success": "ok"
}

Introduction

Jeton d’accès (Acces Token)

Droits (scopes)

Obtenir un jeton d’accès (Obtain an Access Token)

1. Requête d’obtention d’un code d’autorisation (Authorization request)

Remarque

Les erreurs possibles

2. Renvoi du code d’autorisation pour obtenir le jeton d’accès

Remarques

Les erreurs possibles

Renouveler un jeton d’accès (renew a Refresh Token)

Révoquer un jeton d’actualisation (revoke a Refresh Token)

Un exemple des appels effectués par Postman pour l’obtention du jeton d’accès

Un exemple C# utilisant OpenID Connect

Décoder le token avec jwt.ms