Verbind je app met Notiondesk via OAuth.

Met OAuth kunnen andere klanten uw app verbinden met hun werkruimte zonder een API-sleutel te delen. De klant meldt zich aan bij uw account, bekijkt wat uw app vraagt ​​en keurt dit goed. Uw app ontvangt een toegangstoken voor de REST API van uw account, dat de klant op elk moment kan intrekken. Dit artikel beschrijft hoe u uw app registreert, de OAuth 2.0-autorisatiecodeflow uitvoert met PKCE, tokens vernieuwt en fouten afhandelt.

Wanneer gebruik je OAuth in plaats van een API-sleutel?

Elke API-route van het type Notiondesk accepteert beide soorten inloggegevens en beantwoordt ze op dezelfde manier: met dezelfde scopes, reacties en fouten.

Wat uw app moet weten

Lees de eindpunten uit het metadatadocument van de autorisatieserver in plaats van ze vast te coderen.

Voer uw OAuth-client uit op een server. Browsergebaseerde clients worden niet ondersteund: bewaar de tokenuitwisseling, de tokens en elke API-aanroep op uw backend.

Stap 1: Registreer je app

Registreer eenmalig met dynamische klantregistratie :

Het 201 Created antwoord bevat uw client_id en, omdat u om client_secret_post hebt gevraagd, ook een client_secret. Het geheim wordt eenmaal weergegeven: bewaar het bij uw andere servergeheimen.

Met "token_endpoint_auth_method": "none" is uw app een openbare client zonder geheim, en PKCE beschermt de uitwisseling van code.

In plaats van te registreren, kunt u de HTTPS-URL van een clientmetadatadocument gebruiken als uw client_id. Notiondesk haalt het document op wanneer een klant uw app autoriseert en bewaart het maximaal vijf minuten in de cache.

Omleidings-URI-regels

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"}'

• Gebruik https of http op een loopback-host: 127.0.0.1, localhost of [::1].

• Een loopback-redirect werkt op elke poort. Elke andere redirect moet exact overeenkomen.

• Jokertekens, fragmenten, referenties vóór de host (user@), backslashes, niet-ASCII-tekens en in procenten gecodeerde hosts worden geweigerd.

• De host die een klant op het toestemmingsscherm ziet, is afkomstig van uw redirect-URI's of uw client_id-URL. Registreer alleen hosts die u zelf bezit.

Stap 2: Stuur de klant door naar Notiondesk

Genereer een willekeurige code_verifier en leid vervolgens de code_challenge af als de SHA-256-hash van de verificator, gecodeerd in base64url ( PKCE ). Leid de browser van de klant door naar:

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 is vereist en moet exact https://api.notiondesk.so zijn: kleine letters, geen schuine streep aan het einde, geen pad. Een ontbrekende of afwijkende waarde resulteert in invalid_request.

• scope is een lijst met spaties als scheidingstekens. Vraag alleen naar de scopes die uw app gebruikt.

• state beschermt tegen cross-site request forgery. Controleer dit wanneer de klant terugkomt.

Een token dat is uitgegeven voor de REST API Notiondesk werkt alleen met de REST API. Een token dat is uitgegeven voor Workspace MCP wordt door de REST API geweigerd, en omgekeerd.

Stap 3: De klant keurt uw app goed.

Notiondesk toont het toestemmingsscherm. De klant meldt zich aan en ziet de naam en host van uw app, zijn of haar werkruimte en de scopes van uw verzoek die zijn of haar rol toestaat. De klant kan het hele verzoek goedkeuren of afwijzen.

De scopes die uw app kan ontvangen, zijn afhankelijk van de rol van de klant in de werkruimte:

Met admin kan uw app de huisstijl van het helpcentrum wijzigen, integraties configureren waarvan de scripts worden geladen in het openbare helpcentrum en omleidingen verwijderen. Vraag deze optie alleen aan als uw app deze routes gebruikt.

De klant kan het verzoek niet goedkeuren wanneer:

• Hun rol biedt geen van de mogelijkheden waar u om gevraagd heeft;

• Hun werkruimte heeft geen API-toegang. Op het toestemmingsscherm verschijnt vervolgens de melding: "Het werkruimteabonnement omvat geen API-toegang." API-toegang vereist een Enterprise-abonnement.

Na goedkeuring keert de browser terug naar uw redirect_uri met een code, uw state en iss, de identificatiecode van de Notiondesk autorisatieserver. Als de klant de toegang weigert, wordt in plaats daarvan error=access_denied meegestuurd.

Stap 4: Wissel de code in voor tokens

De code is 60 seconden geldig en werkt eenmalig:

Laat client_secret weg voor een publieke klant. Het antwoord:

scope geeft een overzicht van de scopes die de klant heeft toegekend. Dit kunnen er minder zijn dan u hebt aangevraagd. Bewaar beide tokens op uw server.

Stap 5: Roep de Notiondesk API aan

Verzend het toegangstoken als een bearer-token, net zoals een API-sleutel:

De reikwijdte van het token is beperkt tot de huidige rol van de goedkeurende klant: een klant die is gewijzigd naar Viewer verlaat uw app alleen met read, en een route die een ontbrekende reikwijdte nodig heeft, geeft een 403 insufficient_scope-antwoord.

De budgetten voor tariefbeperkingen en de Idempotency-Key-waarden behoren tot de subsidie. Elke goedkeuring is een nieuwe subsidie ​​met eigen budgetten en sleutels, en een tokenvernieuwing behoudt beide.

Stap 6: Vernieuw het toegangstoken

Een toegangstoken is één uur geldig. Wissel het vernieuwingstoken in voor een nieuw paar tokens voordat het verloopt:

Bij elke vernieuwing wordt een nieuw vernieuwingstoken geretourneerd dat 30 dagen geldig is en het door u verzonden token ongeldig maakt. Bewaar het nieuwe vernieuwingstoken voordat u het nieuwe toegangstoken gebruikt.

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

Gebruik een vernieuwingstoken nooit opnieuw. Het verzenden van een token dat al is gebruikt, maakt de volledige autorisatie ongeldig, inclusief het toegangstoken, omdat hergebruik betekent dat het token is gekopieerd. De klant moet uw app dan opnieuw autoriseren.

Hoe klanten uw app kunnen intrekken

Eigenaren en beheerders van werkruimtes zien alle apps met toegang tot hun werkruimte onder Instellingen > Ontwikkelaars > Verbonden apps . Apps die de REST API gebruiken, tonen 'REST API' in de kolom 'Toegang' , samen met de app, de persoon die de autorisatie heeft verleend, de scopes en de laatste activiteit. Het intrekken van de toegang beëindigt de machtiging onmiddellijk: het toegangstoken en het vernieuwingstoken werken niet meer bij het volgende verzoek.

Een subsidie ​​eindigt ook vanzelf:

• na 30 dagen zonder vernieuwing;

• wanneer het vernieuwingstoken opnieuw wordt gebruikt.

Als de goedkeurende klant niet over de vereiste rol voor een route beschikt, of als het werkruimteplan geen API-toegang heeft, worden aanvragen geweigerd. Ze werken weer als de rol of het plan wordt hersteld voordat de toekenning verloopt.

Probleemoplossing Notiondesk OAuth

De autorisatie- en token-eindpunten reageren met standaard OAuth-fouten, niet met de API-foutcode Notiondesk:

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

Het autorisatie-eindpunt toont deze fouten zelf en stuurt een ongeldig verzoek nooit door naar uw redirect_uri. Een geweigerde toestemming bereikt uw app alleen als de error=access_denied redirect.

Aanroepen naar de API zelf beantwoorden met de API-foutcode Notiondesk . Een verlopen of ingetrokken toegangstoken beantwoordt met 401 authentication_error met de melding "Ongeldige of ontbrekende API-sleutel.", dezelfde melding die een onbruikbare API-sleutel krijgt.

Veelgestelde vragen

Wat volgt?

• Ga aan de slag met de Notiondesk REST API

• Authenticeer bij de Notiondesk API met behulp van API-sleutels.

• Verbreek of trek de toegang tot Workspace MCP in.