Authentification OAuth2
Vue d’ensemble
Section intitulée « Vue d’ensemble »UseNadia prend en charge le flux OAuth2 Authorization Code : il permet de construire des applications tierces qui agissent au nom des utilisateurs de UseNadia. Au lieu de demander leur clé API, votre app les redirige vers UseNadia, où ils approuvent l’accès ; vous recevez alors un jeton pour appeler l’API en leur nom.
Fonctionnement
Section intitulée « Fonctionnement »sequenceDiagram participant User as Utilisateur participant YourApp as Votre app participant UseNadia
User->>YourApp: Clique sur « Se connecter avec UseNadia » YourApp->>UseNadia: Redirige vers /oauth/authorize UseNadia->>User: Affiche l’écran de consentement User->>UseNadia: Autorise l’accès UseNadia->>YourApp: Redirige avec ?code=... YourApp->>UseNadia: POST /oauth/token (échange du code) UseNadia->>YourApp: Renvoie l’access_token YourApp->>UseNadia: Appels d’API avec l’access_tokenMise en place
Section intitulée « Mise en place »-
Enregistrer votre app OAuth
Dans UseNadia, ouvrez Paramètres → API & MCP et créez une application OAuth dans la section Apps (voir Paramètres développeurs).
Il vous faut :
- Nom de l’app : affiché aux utilisateurs sur l’écran de consentement
- Description (facultatif) : explique ce que fait votre app
- Photo de profil (facultatif) : affichée sur l’écran de consentement
- URL de redirection : là où UseNadia renvoie les utilisateurs après qu’ils ont accepté ou refusé l’accès
Une fois l’app créée, vous recevez :
- Client ID : l’identifiant public de votre app (commence par
pca_) - Client secret : la clé secrète de l’échange de jeton (commence par
pcs_)
-
Rediriger les utilisateurs vers l’autorisation
Quand un utilisateur veut relier son compte UseNadia à votre app, redirigez-le vers :
https://app.usenadia.com/oauth/authorize?client_id={CLIENT_ID}&response_type=code&state={STATE}Paramètre Obligatoire Description client_idOui Le Client ID de votre app response_typeOui Doit valoir codestateNon Une chaîne aléatoire contre les attaques CSRF. Recommandé. Exemple :
Fenêtre de terminal https://app.usenadia.com/oauth/authorize?client_id=pca_VklHTpdEJ6dJ73FHQEJ97qVA0lcMDsrs&response_type=code&state=random123L’utilisateur voit un écran de consentement avec le nom de votre app, sa description et les permissions demandées. Il choisit Autoriser ou Refuser.
-
Traiter le retour
Une fois sa décision prise, UseNadia redirige l’utilisateur vers votre URL de redirection, avec des paramètres de requête.
S’il accepte :
https://yourapp.com/callback?code=abc123&state=random123Paramètre Description codeCode d’autorisation à échanger contre un jeton (expire au bout de 10 minutes) stateLa valeur de stateenvoyée à l’étape précédenteS’il refuse :
https://yourapp.com/callback?error=access_denied&state=random123 -
Échanger le code contre un jeton
Faites une requête
POSTcôté serveur pour échanger le code d’autorisation contre un jeton d’accès :Fenêtre de terminal curl -X POST https://app.usenadia.com/api/oauth/token \-H "Content-Type: application/json" \-d '{"grant_type": "authorization_code","code": "abc123","client_id": "pca_VklHTpdEJ6dJ73FHQEJ97qVA0lcMDsrs","client_secret": "pcs_your_client_secret"}'Paramètre Obligatoire Description grant_typeOui Doit valoir authorization_codecodeOui Le code d’autorisation de l’étape précédente client_idOui Le Client ID de votre app client_secretOui Le Client secret de votre app Réponse :
{"access_token": "pos_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcd","token_type": "Bearer","scope": "mcp:read mcp:write"}Champ Description access_tokenLe jeton à utiliser pour les appels API suivants token_typeToujours BearerscopeLes droits du jeton : mcp:read mcp:writeChaque autorisation donne un jeton neuf : une seconde connexion de la même app (un autre appareil, une autre conversation) ne déconnecte pas la première.
-
Appeler l’API
Passez le jeton d’accès dans l’en-tête
Authorization, exactement comme une clé API :Fenêtre de terminal curl -H "Authorization: pos_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcd" \https://app.usenadia.com/api/public/v1/integrationsLe jeton fonctionne sur tous les endpoints de l’API publique :
- Canaux
- Publications
- Analyses
- et toutes les autres ressources de cette référence
Gérer votre app
Section intitulée « Gérer votre app »Renouveler le client secret
Section intitulée « Renouveler le client secret »Si votre client secret est compromis, ouvrez Paramètres → API & MCP, section Apps, et cliquez sur Renouveler le secret. L’ancien secret est invalidé sur-le-champ : tout échange de jeton qui l’utilise encore échoue.
Supprimer votre app
Section intitulée « Supprimer votre app »Supprimer votre app OAuth :
- révoque tous les jetons d’accès émis aux utilisateurs ;
- retire l’app de la liste des apps autorisées de chaque utilisateur ;
- est définitif.
Exemple complet (Node.js)
Section intitulée « Exemple complet (Node.js) »const express = require('express');const crypto = require('crypto');const app = express();
const CLIENT_ID = 'pca_your_client_id';const CLIENT_SECRET = 'pcs_your_client_secret';const NADIA_URL = 'https://app.usenadia.com';const BACKEND_URL = 'https://app.usenadia.com/api';const REDIRECT_URL = 'https://yourapp.com/callback';
// Étape 2 : rediriger l’utilisateur vers UseNadiaapp.get('/connect', (req, res) => { const state = crypto.randomBytes(16).toString('hex'); // Garder le state en session pour la vérification CSRF req.session.oauthState = state;
const params = new URLSearchParams({ client_id: CLIENT_ID, response_type: 'code', state, });
res.redirect(`${NADIA_URL}/oauth/authorize?${params}`);});
// Étapes 3 et 4 : traiter le retour et échanger le codeapp.get('/callback', async (req, res) => { const { code, state, error } = req.query;
// Refus de l’utilisateur ? if (error === 'access_denied') { return res.send('User denied access'); }
// Vérifier le state if (state !== req.session.oauthState) { return res.status(403).send('Invalid state'); }
// Échanger le code contre un jeton const response = await fetch(`${BACKEND_URL}/oauth/token`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ grant_type: 'authorization_code', code, client_id: CLIENT_ID, client_secret: CLIENT_SECRET, }), });
const { access_token } = await response.json();
// Stocker access_token en lieu sûr et s’en servir pour les appels API // Exemple : récupérer les canaux (integrations) de l’utilisateur const integrations = await fetch( `${BACKEND_URL}/public/v1/integrations`, { headers: { Authorization: access_token } } ).then(r => r.json());
res.json({ connected: true, integrations });});
app.listen(3000);Référence des erreurs
Section intitulée « Référence des erreurs »| Erreur | Quand | Description |
|---|---|---|
invalid_client |
Échange de jeton | Le Client ID ou le Client secret est faux |
invalid_grant |
Échange de jeton | Le code est invalide, expiré ou déjà utilisé |
unsupported_grant_type |
Échange de jeton | grant_type ne vaut pas authorization_code |
access_denied |
Retour | L’utilisateur a refusé la demande d’autorisation |