Passer au contenu principal

OAuth 2.0 (client credentials)

L’API Energy Management utilise le flux OAuth 2.0 client_credentials. Chaque requête (à l’exception de GET /health et POST /oauth/token) doit inclure un jeton Bearer :

1. Créer des identifiants

Tout utilisateur de votre organisation peut créer des identifiants client OAuth dans le tableau de bord RiDERgy : ouvrez Mon compte, allez dans OAuth Clients puis Créer un client. RiDERgy doit d’abord activer l’API Energy Management pour votre organisation ; sans activation, les requêtes échouent avec 403 FEATURE_NOT_ENABLED.
  • ID client (emcl_...) : non secret. Il reste visible dans le tableau de bord.
  • Secret client (emcs_...) : affiché une seule fois, à la création. Enregistrez-le immédiatement dans un gestionnaire de mots de passe ou un coffre de secrets. RiDERgy ne peut pas le réafficher ; en cas de perte, créez un nouveau client et révoquez l’ancien.
  • Ne choisissez que les scopes nécessaires à votre intégration. Les nouveaux clients sont en lecture seule par défaut.
  • Un client appartient à votre organisation, pas à la personne qui l’a créé : il continue de fonctionner si cette personne part.
  • RiDERgy ne délivre pas de clés API. Les requêtes avec un en-tête x-api-key sont refusées avec 401 ; utilisez toujours un jeton Bearer comme décrit ci-dessous.
Pas encore d’accès au tableau de bord ? Pendant l’intégration de votre organisation, RiDERgy peut délivrer un client temporaire qui expire après 7 jours. Vous recevrez l’ID client et le secret par deux canaux distincts. Dès que vous avez un accès, créez votre propre client et demandez à RiDERgy de révoquer le client temporaire.

2. Obtenir un jeton d’accès

Les jetons expirent après 3600 secondes (1 heure). Demandez un nouveau jeton avant l’expiration du jeton en cours. Vous pouvez aussi transmettre les identifiants via Authorization: Basic base64(client_id:client_secret) avec grant_type=client_credentials dans le corps (RFC 6749).

3. Utiliser le jeton

Transmettez le jeton comme Authorization: Bearer <token> pour chaque requête :
  • Votre tenant est intégré dans le jeton et ne peut être usurpé — des identifiants d’un tenant ne peuvent pas accéder aux données d’un autre.
  • Un jeton expiré ou invalide renvoie 401 UNAUTHORIZED.
  • Un jeton sans le scope requis renvoie 403 INSUFFICIENT_SCOPE.

Scopes

Les jetons portent des scopes qui contrôlent les endpoints accessibles : Les requêtes vers des endpoints nécessitant un scope que le jeton ne possède pas échoueront avec 403 INSUFFICIENT_SCOPE.

Tester dans la documentation

  1. Ouvrez Obtenir un jeton d’accès et cliquez sur Try it.
  2. Saisissez votre client_id et votre client_secret, laissez grant_type sur client_credentials et envoyez la requête.
  3. Copiez l’access_token de la réponse.
  4. Ouvrez n’importe quelle page d’endpoint de la Référence API, collez le jeton dans le champ Authorization et envoyez la requête.
Les requêtes depuis la documentation vont vers l’API de production et n’atteignent que les sites de votre organisation. Un POST/PUT modifie de vraies limites de recharge : testez avec un client en lecture seule si vous ne voulez rien changer.

Renouveler et révoquer les identifiants

  • Renouveler : créez un nouveau client, basculez votre intégration dessus, puis révoquez l’ancien.
  • Révoquer : dans le tableau de bord, à côté du client. La révocation est immédiate : les jetons déjà émis pour ce client cessent de fonctionner dès la requête suivante.
  • Les clients temporaires expirés cessent de fonctionner de la même façon.