Connectez votre application à Notiondesk avec OAuth

OAuth permet à d'autres clients de connecter votre application à leur espace de travail sans partager de clé API. Le client se connecte à son compte, examine les demandes de votre application et les approuve. Votre application reçoit alors un jeton d'accès pour l'API REST, que le client peut révoquer à tout moment. Cet article décrit la procédure d'enregistrement de votre application, l'exécution du flux d'autorisation OAuth 2.0 avec PKCE, le renouvellement des jetons et la gestion des erreurs.

Quand utiliser OAuth plutôt qu'une clé API

Chaque route API Notiondesk accepte les deux types d'identifiants et leur répond de la même manière : mêmes étendues, réponses et erreurs.

Ce que votre application doit savoir

Lisez les points de terminaison à partir du document de métadonnées du serveur d'autorisation plutôt que de les coder en dur.

Exécutez votre client OAuth sur un serveur. Les clients basés sur un navigateur ne sont pas pris en charge : conservez l’échange de jetons, les jetons eux-mêmes et tous les appels d’API sur votre serveur.

Étape 1 : Enregistrez votre application

Inscrivez-vous une seule fois avec l'inscription client dynamique :

La réponse 201 Created contient votre client_id et, puisque vous avez demandé client_secret_post, un client_secret. Ce secret n'est affiché qu'une seule fois : conservez-le avec vos autres secrets de serveur.

Avec "token_endpoint_auth_method": "none", votre application est un client public sans secret, et PKCE protège son échange de code.

Au lieu de vous inscrire, vous pouvez utiliser l'URL HTTPS d'un document de métadonnées client comme client_id. Notiondesk récupère le document lorsqu'un client autorise votre application et le met en cache pendant cinq minutes maximum.

Règles de redirection d'URI

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• Utilisez https ou http sur un hôte de bouclage : 127.0.0.1, localhost ou [::1].

• Une redirection de bouclage s'applique à n'importe quel port. Toute autre redirection doit correspondre exactement.

• Les caractères génériques, les fragments, les informations d'identification avant l'hôte (user@), les barres obliques inverses, les caractères non ASCII et les hôtes encodés en pourcentage sont refusés.

• L'hôte affiché au client sur l'écran de consentement provient de vos URI de redirection ou de votre URL client_id. N'enregistrez que les hôtes dont vous êtes propriétaire.

Étape 2 : Envoyer le client à Notiondesk

Créez un code_verifier aléatoire, puis calculez le code_challenge comme le hachage SHA-256 du vérificateur, encodé en base64url ( PKCE ). Redirigez le navigateur du client vers :

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource est obligatoire et doit correspondre exactement à https://api.notiondesk.so : en minuscules, sans barre oblique finale, sans chemin. Une valeur manquante ou différente renvoie invalid_request.

• scope est une liste d'éléments séparés par des espaces. Demandez uniquement les autorisations utilisées par votre application.

• state protège contre la falsification de requêtes intersites. Vérifiez-le lorsque le client revient.

Un jeton émis pour l'API REST Notiondesk fonctionne uniquement avec cette API. Un jeton émis pour Workspace MCP est refusé par l'API REST, et inversement.

Étape 3 : Le client approuve votre application

L'écran de consentement s'affiche. Le client se connecte et voit le nom et l'hôte de votre application, son espace de travail et les autorisations de votre requête auxquelles son rôle lui permet d'accéder. Il approuve ou refuse la requête.

Les autorisations que votre application peut recevoir dépendent du rôle du client dans l'espace de travail :

admin permet à votre application de modifier l'identité visuelle du centre d'aide, de configurer les intégrations dont les scripts se chargent sur le centre d'aide public et de supprimer les redirections. Demandez-la uniquement si votre application utilise ces routes.

Le client ne peut pas approuver la demande lorsque :

• Leur rôle ne permet aucune des possibilités que vous avez demandées ;

• Leur espace de travail ne dispose pas d'accès API. L'écran de consentement affiche alors : « Le forfait espace de travail n'inclut pas l'accès API. » L'accès API nécessite un forfait Entreprise.

Après approbation, le navigateur vous renvoie à votre page redirect_uri avec code, votre page state et iss, l'identifiant du serveur d'autorisation Notiondesk. Si le client refuse, la redirection utilise error=access_denied.

Étape 4 : Échanger le code contre des jetons

Ce code est valable pendant 60 secondes et ne fonctionne qu'une seule fois :

Omettez client_secret pour un client public. Réponse :

scope répertorie les autorisations accordées par le client, qui peuvent être inférieures à celles que vous avez demandées. Stockez les deux jetons sur votre serveur.

Étape 5 : Appeler l’API Notiondesk

Envoyez le jeton d'accès sous forme de jeton porteur, exactement comme une clé API :

Les portées du jeton sont limitées au rôle actuel du client qui approuve : un client passé au rôle de Visionneur laisse votre application avec uniquement read, et une route qui a besoin d'une portée manquante répond 403 insufficient_scope.

Les budgets de limitation de débit et les valeurs Idempotency-Key appartiennent à l'autorisation. Chaque approbation constitue une nouvelle autorisation avec ses propres budgets et clés, et une actualisation du jeton conserve les deux.

Étape 6 : Actualiser le jeton d’accès

Un jeton d'accès est valable une heure. Avant son expiration, échangez le jeton d'actualisation contre une nouvelle paire :

Chaque actualisation génère un nouveau jeton d'actualisation valable 30 jours et invalide celui que vous avez envoyé. Conservez le nouveau jeton d'actualisation avant d'utiliser le nouveau jeton d'accès.

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

curl "https://api.notiondesk.so/sites" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "nd-version: 2026-10-16"

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

Ne réutilisez jamais un jeton d'actualisation. L'envoi d'un jeton déjà utilisé révoque l'intégralité de l'autorisation, y compris le jeton d'accès, car sa réutilisation implique sa copie. Le client devra alors autoriser votre application à nouveau.

Comment les clients révoquent votre application

Les propriétaires et administrateurs d'espace de travail peuvent consulter toutes les applications ayant accès à leur espace de travail dans Paramètres > Développeurs > Applications connectées . Les applications utilisant l'API REST affichent « API REST » dans la colonne Accès , avec l'application, la personne qui l'a autorisée, ses autorisations et sa dernière activité. La révocation met fin immédiatement à l'autorisation : le jeton d'accès et le jeton d'actualisation deviennent inopérants pour la prochaine requête.

Une subvention prend également fin d'elle-même :

• après 30 jours sans actualisation ;

• lorsque son jeton d'actualisation est réutilisé.

Tant que le client autorisant l'accès ne possède pas le rôle requis pour un itinéraire, ou que le plan d'espace de travail ne dispose pas d'un accès API, les requêtes sont refusées. Elles redeviennent valides si le rôle ou le plan est rétabli avant la fin de la période d'autorisation.

Dépannage Notiondesk OAuth

Les points de terminaison d'autorisation et de jeton répondent aux erreurs OAuth standard, et non à l'enveloppe d'erreur de l'API Notiondesk :

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

Le point de terminaison d'autorisation affiche lui-même ces erreurs et ne redirige jamais une requête invalide vers votre redirect_uri. Un refus de consentement n'atteint votre application que via la redirection error=access_denied.

Les appels à l'API elle-même renvoient l' enveloppe d'erreur Notiondesk . Un jeton d'accès expiré ou révoqué renvoie 401 authentication_error avec le message « Clé API invalide ou manquante », soit le même message qu'une clé API inutilisable.

Questions fréquentes

Et ensuite ?

• Commencez à utiliser l'API REST Notiondesk

• Authentifiez-vous auprès de l'API Notiondesk à l'aide de clés API.

• Déconnectez ou révoquez l'accès à l'espace de travail MCP