Control API - miljöer

Använd FoxIDs Control API för att lista, skapa, konfigurera och ta bort miljöer i en tenant. En miljö kallas en track i Control API rutter och scheman.

Innan du anropar dessa åtgärder, konfigurera Control API autentisering och åtkomsträttigheter. Swagger förblir den exakta referensen för alla miljöegenskaper, valideringsregler och svarsscheman:

Slutpunktsbas

Miljöadministration utförs genom tenants master-miljö. Exemplen använder FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/master

Ersätt {tenant_name} med tenants tekniska namn. Ändra värd för en självvärd driftsättning. Skicka åtkomsttoken Control API i rubriken Authorization: Bearer {access_token}.

Miljöoperationer kräver motsvarande tenant eller miljöåtkomsträttigheter. Miljöerna som returneras av listoperationer är begränsade till de som den som ringer kan komma åt. Använd Control API åtkomsträttshierarkin för att bara ge den nödvändiga read-, create-, update- eller delete-operationen.

Miljöverksamhet

Miljöåtgärder grupperas under tenant tracks i Swagger.

Drift Slutpunkt Ändamål
Lista GET /!tracks Lista tillgängliga miljöer med valfri filtrering och sidnumrering.
Få GET /!track?name={name} Få hela konfigurationen för en miljö.
Skapa POST /!track Skapa en miljö och dess standardinloggningsautentiseringsmetod.
Uppdatera PUT /!track Ersätt den redigerbara miljökonfigurationen.
Radera DELETE /!track?name={name} Ta bort en miljö och dess data permanent.

Lägg till varje slutpunkt till slutpunktsbasen.

Lista och identifiera miljöer

GET /!tracks accepterar filterName och paginationToken. Filtret matchar antingen den tekniska name eller displayName, utan hänsyn till skiftläge.

Svaret innehåller en data-samling och en ogenomskinlig paginationToken. För att läsa nästa sida, upprepa samma begäran med den returnerade token och samma filter. Fortsätt tills svaret inte längre innehåller en token. Tolka eller modifiera inte token.

Den tekniska name identifierar miljön i Control API webbadresser och i efterföljande åtgärder för att hämta, uppdatera och ta bort. Behandla det som en stabil automatiseringsnyckel. Använd displayName för text som presenteras för administratörer.

Skapa en miljö

Miljönamn är små bokstäver. Ange en name när en integration kräver en förutsägbar webbadress, eller utelämna den och låt FoxIDs generera ett unikt namn. En begäran måste innehålla antingen ett namn eller ett visningsnamn.

Genom att skapa en miljö skapas också standardinloggningsautentiseringsmetoden. Andra applikationer, autentiseringsmetoder, användare, nycklar och miljöresurser konfigureras separat efter skapandet.

Planen tenant kan begränsa antalet miljöer. En skapa-begäran kan därför misslyckas när gränsen nås. Samtidiga planbegränsade skapande operationer kan returnera 423 Locked; försök igen efter en kort fördröjning.

Uppdatera miljöinställningar

PUT /!track är en fullständig uppdatering, inte en patch. Skaffa först den aktuella miljön, bevara alla egenskaper som ska förbli oförändrade, tillämpa de avsedda ändringarna och skicka den fullständiga redigerbara representationen.

Den tekniska name väljer miljön och döps inte om av en uppdatering. Redigerbara inställningar inkluderar visnings- och företagsinformation, sekvenslivslängd, anspråksmappningsbeteende, skydd mot inloggningsfel, lösenordspolicyer, extern lösenords- och katalogintegrering och tillåtna iframe-domäner. Vissa relaterade resurser, inklusive SMS, e-post, anspråksmappningar, texter, nycklar och certifikat, har dedikerade slutpunkter och ersätts inte genom miljöoperationen.

Uppdaterade inställningar används av efterföljande förfrågningar efter att FoxIDs ogiltigförklarar miljökonfigurationscachen.

Ta bort en miljö

Att ta bort en miljö är en oåterkallelig, kaskadoperation. Den tar bort miljökonfigurationen och all data som omfattas av den miljön, inklusive dess applikationer, autentiseringsmetoder, användare, sessioner, anslag, nycklar och andra resurser. Länkar från andra miljöer till den borttagna miljön tas också bort.

Använd inte miljöborttagning som ett sätt att rensa valda resurser. Ta bort eller uppdatera dessa resurser individuellt när miljön måste förbli tillgänglig. Innan du tar bort en miljö, stoppa trafiken till den, exportera eventuell konfiguration eller data som måste behållas och verifiera det tekniska namnet i begäran.

Automationsvägledning

  • Håll tekniska namn stabila och lagra dem separat från visningsnamn.
  • Använd listpaginering även när en tenant för närvarande bara har ett fåtal miljöer.
  • Använd ett få-ändra-lägg-arbetsflöde för att undvika att oavsiktligt återställa inställningar som lagts till i en nyare FoxIDs-version.
  • Skapa beroende resurser först efter att begäran om skapande av miljön har lyckats.
  • Behandla borttagning som en permanent rivningsoperation och kräver en uttrycklig bekräftelse i administrativa verktyg.
  • Räkna med att skapa, uppdatera och ta bort förfrågningar visas i kontrollgranskningsloggen. Läsoperationer skrivs inte som revisionshändelser.

Vanliga felsvar

  • 400 Bad Request när miljödata eller namn är ogiltigt, ett reserverat namn används eller en plangräns har nåtts.
  • 401 Unauthorized när åtkomsttoken saknas eller är ogiltig.
  • 403 Forbidden när den som ringer saknar den åtkomsträtt som krävs.
  • 404 Not Found när den valda miljön inte finns.
  • 409 Conflict när det redan finns en miljö med samma tekniska namn.
  • 423 Locked när en planbegränsad skapandeåtgärd är tillfälligt låst.

Använd svarstexten för valideringsdetaljer och Swagger UI för svaren som deklareras av varje operation.