Skip to main content
Gebruik OAuth-clientreferenties wanneer uw backendintegratie kortlevende toegangstokens nodig heeft of uw beveiligingsbeleid die vereist. Elke client hoort bij één serviceaccount en één organisatie. OAuth is optioneel: een API-sleutel met beperkte scope volstaat voor een private serverintegratie die een sleutel veilig kan opslaan en roteren. Raadpleeg Authenticatie om te kiezen tussen beide methoden en om te begrijpen hoe serviceaccounts hierin passen.
OAuth-toegang moet voor uw organisatie zijn ingeschakeld. Bij uw installatie ontvangt u het regionale tokenendpoint, de issuer, de audience en de clientauthenticatiemethode. Als u deze instellingen nodig hebt of geen toegang hebt tot clientbeheer, neemt u contact op met Living Security Support.
De client credentials grant vertegenwoordigt uw serviceaccount. Hiermee wordt geen persoon aangemeld en wordt een klant niet gevraagd een applicatie te autoriseren. Gedelegeerde autorisatie via een browser is een afzonderlijke OAuth-mogelijkheid en wordt door deze operaties niet aangeboden.

Voordat u begint

  • Maak een serviceaccount aan met uitsluitend de rechten die de integratie nodig heeft.
  • Gebruik een beheerreferentie met service_account:manage en elk recht dat u aan de nieuwe client wilt toekennen. Het doelaccount moet deze rechten eveneens hebben. Een client kan de bevoegdheden van geen van beide accounts uitbreiden.
  • Kies de regio van de organisatie. API-referenties en OAuth-toegangstokens horen bij de overeenkomstige regionale API-host.
  • Bewaar het clientsecret en de tokens in uw server-side secretopslag. Plaats ze nooit in browsercode, mobiele applicaties, broncodebeheer of requestlogs.

Een client aanmaken

POST /v1/oauth_clients vereist service_account_id, een niet-lege lijst met expliciete scopes en een Idempotency-Key. Wildcards worden niet geaccepteerd. Een client ondersteunt maximaal 100 scopes, met een gecombineerde lengte van maximaal 4.096 tekens. Elk serviceaccount kan maximaal 20 clients of onopgeloste aanmaak-/opschoonoperaties hebben. Intrekking weigert direct de API-toegang. Een client of een onzekere aanmaak bij de provider blijft meetellen voor de limiet totdat de opschoning aan de externe kant is bevestigd. Een verlaten reservering of een aanmaak waarvan is bewezen dat die mislukte voordat het werk bij de provider begon, kan zijn slot veilig vrijgeven. De retrysleutel blijft echter bij de oorspronkelijke poging horen; herstel die receipt voordat u beslist of u een vervanger aanmaakt. Kies één retrysleutel voor deze aanmaakpoging en sla deze op voordat u het request verzendt. Gebruik 1–255 zichtbare ASCII-tekens, zonder spaties. Gebruik dezelfde sleutel opnieuw met hetzelfde account, dezelfde scopes, hetzelfde beheerprincipal, dezelfde regio en dezelfde API-versie na een verloren respons. Het roteren van de beheerreferentie onder hetzelfde serviceaccount creëert geen nieuwe retry-identiteit. Installeer het Python-pakket requests. Laad de volgende omgevingswaarden via uw gebruikelijke secret- en configuratiebeheer:
Python
Het voorbeeld doet één request en bewaart het resultaat in het geheugen. Voeg de schrijfoperatie van uw secretmanager toe op het gemarkeerde punt voordat u het in productie uitvoert. Het vereist bewust een beslissing na een onzeker resultaat in plaats van stilzwijgend nog een client aan te maken. Netwerkuitzonderingen vereisen ook de onderstaande herstelstappen. Aanmaak- en receiptresponses gebruiken 201 en bevatten een oauth_client-resource met id, service_account_id, client_id, scopes, status, created_at en client_secret. Responses zijn gemarkeerd met Cache-Control: no-store.
  • id identificeert de platformresource. Sla deze op voor opvragen en intrekken.
  • client_id identificeert de client tijdens de tokenuitwisseling. Dit is niet de ID van de platformresource. Deze kan null zijn zolang de aanmaak in behandeling is.
  • client_secret wordt alleen geretourneerd aan het request dat de aanmaak voltooit. Elk herhaald aanmaakrequest retourneert null, ook een retry na een verloren succesrespons. Bij het opvragen wordt nooit een secret geretourneerd.

Herstellen na een verloren of onderbroken respons

Herhaal hetzelfde aanmaakrequest met de opgeslagen retrysleutel om een resource-receipt te herstellen. De receipt weerspiegelt de actuele status, dus een ingetrokken client blijft ingetrokken. Deze operatie gebruikt niet het algemene replaycontract van 24 uur voor gecachete responses en retourneert geen Idempotent-Replayed-header. Zie fouten voor request-ID’s en herstelgegevens. Verzend nooit een clientsecret of toegangstoken met een supportaanvraag.

Opvragen en intrekken

Gebruik uw beheerreferentie en de platformresource id: Intrekking blokkeert volgende API-requests van de client, inclusief requests met reeds uitgegeven tokens. Werk dat de API al heeft geaccepteerd, wordt niet geannuleerd. De opschoning van externe referenties kan later worden voltooid. Het herhalen van een intrekking is veilig en vereist geen retrysleutel. Blijf de beheerreferentie gebruiken als de client die wordt ingetrokken zelf een API-aanroeper is.

Roteren zonder toegang te verliezen

Maak een tweede client aan met de vereiste scope-bovengrens. Sla het secret op, verkrijg een token via uw regionale tokenendpoint en controleer of de integratie ermee werkt. Schakel de integratie over naar de vervanger en trek daarna de oude resource in. Houd een onafhankelijke beheerreferentie achter de hand, zodat u kunt herstellen van een mislukte uitrol. Toegangstokens kunnen niet meer toekennen dan de scopes van de client en de actuele rechten van het serviceaccount. Het verwijderen van accountrechten of het intrekken van een client heeft voorrang op de resterende levensduur van een token. Beschouw een gecacht token niet als bewijs dat de autorisatie nog geldig is. Verkrijg vóór het verlopen een nieuw toegangstoken door de client opnieuw te authenticeren; deze grant gebruikt geen refresh-tokens.