Aller au contenu

Authentification OAuth2

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.

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_token
  1. 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_)
  2. 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_id Oui Le Client ID de votre app
    response_type Oui Doit valoir code
    state Non 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=random123

    L’utilisateur voit un écran de consentement avec le nom de votre app, sa description et les permissions demandées. Il choisit Autoriser ou Refuser.

  3. 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=random123
    Paramètre Description
    code Code d’autorisation à échanger contre un jeton (expire au bout de 10 minutes)
    state La valeur de state envoyée à l’étape précédente

    S’il refuse :

    https://yourapp.com/callback?error=access_denied&state=random123
  4. Échanger le code contre un jeton

    Faites une requête POST cô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_type Oui Doit valoir authorization_code
    code Oui Le code d’autorisation de l’étape précédente
    client_id Oui Le Client ID de votre app
    client_secret Oui Le Client secret de votre app

    Réponse :

    {
    "access_token": "pos_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcd",
    "token_type": "Bearer",
    "scope": "mcp:read mcp:write"
    }
    Champ Description
    access_token Le jeton à utiliser pour les appels API suivants
    token_type Toujours Bearer
    scope Les droits du jeton : mcp:read mcp:write

    Chaque 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.

  5. 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/integrations

    Le jeton fonctionne sur tous les endpoints de l’API publique :


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 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.

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 UseNadia
app.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 code
app.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);

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