Documentation Développeur

Intégrez l'authentification SAGAPASS à votre application en suivant notre guide complet.

Introduction

Bienvenue sur la documentation de l'API SAGAPASS. Notre objectif est de vous fournir tous les outils nécessaires pour intégrer une authentification OAuth2 robuste, sécurisée et simple pour vos utilisateurs.

SAGAPASS utilise le standard OAuth 2.0 avec le flux Authorization Code Grant, complété par la spécification PKCE (Proof Key for Code Exchange) pour une sécurité accrue, notamment pour les applications mobiles et les Single-Page Applications (SPA).

Flux d'Authentification

Le processus d'authentification se déroule en plusieurs étapes :

  1. Redirection de l'utilisateur : Votre application redirige l'utilisateur vers le point d'accès /oauth/authorize de SAGAPASS avec les paramètres de votre application (client_id, redirect_uri, etc.).
  2. Consentement de l'utilisateur : L'utilisateur se connecte sur SAGAPASS et autorise votre application à accéder aux informations demandées (définies par les scopes).
  3. Réception du code d'autorisation : SAGAPASS redirige l'utilisateur vers votre redirect_uri avec un code d'autorisation (code) à usage unique.
  4. Échange du code contre un Access Token : Votre serveur, de manière sécurisée, échange ce code d'autorisation contre un access_token en appelant le point d'accès /oauth/token.
  5. Appels API : Avec l'access_token, votre application peut maintenant appeler les points d'accès protégés de l'API SAGAPASS (par exemple, pour récupérer les informations de l'utilisateur).

Points d'Accès (Endpoints)

Point d'accès d'autorisation

C'est le point de départ du flux. Vous devez rediriger vos utilisateurs vers cette URL.

GET https://sagapass.com/oauth/authorize

Point d'accès de Token

Utilisé par votre serveur pour échanger un code d'autorisation contre un access token.

POST https://sagapass.com/oauth/token

Point d'accès d'informations utilisateur

Une fois que vous avez un access token valide, vous pouvez l'utiliser pour récupérer les informations de l'utilisateur.

GET https://sagapass.com/api/oauth/userinfo

Scopes

Les scopes permettent de limiter l'accès d'une application aux données d'un utilisateur. Vous devez spécifier les scopes dont vous avez besoin lors de la demande d'autorisation.

  • profile: Accès aux informations de base du profil (nom, email).
  • email: Accès à l'adresse email de l'utilisateur.
  • openid: Requis pour la compatibilité OpenID Connect.
  • kyc.status: Permet de savoir si l'identité de l'utilisateur a été vérifiée (KYC).

Gestion des Tokens

Lorsque vous échangez le code d'autorisation, l'API vous retourne un access_token et un refresh_token.

  • Access Token : Il a une durée de vie courte (généralement 1 heure). Il doit être inclus dans l'en-tête Authorization de chaque requête API : Authorization: Bearer VOTRE_ACCESS_TOKEN.
  • Refresh Token : Il a une durée de vie plus longue et est utilisé pour obtenir un nouvel access token lorsque l'actuel a expiré, sans que l'utilisateur ait besoin de se reconnecter.

Récupérer les infos utilisateur

Pour obtenir les informations de l'utilisateur connecté, effectuez une requête GET vers le point d'accès userinfo avec l'access token.

fetch('https://sagapass.com/api/oauth/userinfo', {
    headers: {
        'Authorization': 'Bearer ' + accessToken,
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => console.log(data));

La réponse sera un objet JSON contenant les informations de l'utilisateur correspondant aux scopes autorisés.

Gestion des Erreurs

L'API utilise les codes de statut HTTP standards pour indiquer le succès ou l'échec d'une requête. Une réponse d'erreur (4xx ou 5xx) inclura un corps JSON avec des détails sur l'erreur.

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
}

Sécurité & Bonnes Pratiques

  • PKCE est obligatoire : Toutes les demandes d'autorisation doivent inclure les paramètres code_challenge et code_challenge_method.
  • Stockage sécurisé des tokens : Ne stockez jamais les tokens côté client dans un stockage persistant (comme le localStorage). Pour les SPAs, utilisez la mémoire de l'application. Pour les applications web traditionnelles, stockez-les dans des sessions côté serveur.
  • Validation du `state` : Utilisez le paramètre state pour prévenir les attaques CSRF. Générez une chaîne aléatoire avant la redirection et validez-la au retour.