Control API - tenant administration

FoxIDs har separate Control API-overflader for implementeringsoperatører, der administrerer tenants og for en tenant, der administrerer sin egen konto. Brug operatørhandlingerne til tenant-klargøring og tværgåendetenant administration. Brug selvbetjeningsoperationerne, når en integration skal være begrænset til sin egen tenant.

Før du kalder disse handlinger, konfigurer Control API-godkendelse og adgangsrettigheder. Swagger forbliver den nøjagtige reference for tenant-ejendomme, plan- og betalingsmuligheder, valideringsregler og svarskemaer:

API-overflader

Implementeringsoperatør

Operatørhandlinger kaldes i master tenant:

https://control.foxids.com/api/master/master

Operation	Endpoint	Formål
Liste	`GET /!tenants`	Liste ikke-master tenants med valgfri filtre og paginering.
Hent	`GET /!tenant?name={name}`	Læs en tenants administrationsressource.
Opret	`POST /!tenant`	Provisioner en tenant, en indledende administrator og standardressourcer.
Opdater	`PUT /!tenant`	Erstat de redigerbare operatøradministrerede tenant-egenskaber.
Slet	`DELETE /!tenant?name={name}`	Slet en tenant og alle tenant data permanent.

Disse handlinger kræver master-tenant adgangsrettigheder. De er beregnet til pålidelig implementeringsadministration og SaaS leveringstjenester.

Tenant selvbetjening

En tenant kalder sine egne operationer gennem sit master-miljø:

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

Operation	Endpoint	Formål
Hent	`GET /!mytenant`	Læs den opkaldendes tenant-konto og tilgængelige indstillinger.
Opdater	`PUT /!mytenant`	Opdater tilladte selvbetjeningsegenskaber.
Slet	`DELETE /!mytenant`	Slet permanent den opkaldendes tenant og alle tenant data.

Selvbetjening bruger tenant adgangsrettigheder og kan ikke administrere en anden tenant. Planændringer, betalingsindstillinger og tilpassede domæner er også underlagt implementeringens konfigurerede politikker.

Skift værten i disse eksempler for en selv-hostet implementering, og send adgangstokenet i Authorization: Bearer {access_token}-headeren.

List og identificer tenants

GET /!tenants accepterer filterName, filterCustomDomain og paginationToken. Når begge filtre er angivet, returneres en tenant, når enten dens navn eller tilpassede domæne matcher. Registreringerne master tenant og intern brug kun tenant er ikke inkluderet.

Gentag en pagineret anmodning med de samme filtre og det returnerede uigennemsigtige token, indtil der ikke returneres noget token. Du må ikke fortolke eller ændre tokenet.

De små bogstaver tenant name er den stabile identifikator, der bruges i FoxIDs og Control API webadresser. Behandl det som en uforanderlig automatiseringsnøgle. Et tilpasset domæne er en separat routing- og brandingegenskab og må ikke bruges som navnet på Control API ruten tenant.

Provisioner en tenant

Tenant-oprettelse er en sammensat klargøringsoperation. En vellykket anmodning skaber:

tenant-posten;
tenantens master-miljø og dets standard Login-autentificeringsmetode;
den oprindelige administratorbruger;
Control API-ressourcen og Control Client-applikationen;
implementeringens konfigurerede standardmiljøer.

Den oprindelige administrator kan modtage en leveret adgangskode eller oprette en adgangskode gennem det konfigurerede e-mail-flow. Beskyt enhver medfølgende adgangskode, og log ikke forespørgselsteksten.

Anmodningen kan også vælge en plan og initialisere kunde-, krav og brugerdefinerede domæneindstillinger, hvor implementeringen tillader dem. Tenant navnentydighed, planregler, support til tilpasset domæne og påkrævede administratordata valideres, før klargøringen fuldføres. Hvis en konto- eller datafejl afbryder klargøringen, forsøger FoxIDs at rydde op i ressourcer, der er oprettet af denne anmodning; ikke desto mindre bør klienter behandle enhver fejl som mislykket og bekræfte tilstanden, før de prøver igen med det samme tenant-navn.

Opdater indstillinger for tenant

Tenant-PUT-operationer er komplette opdateringer, ikke patches. Hent den aktuelle ressource, bevar alle redigerbare egenskaber, der skal forblive uændrede, anvend den tilsigtede ændring, og send den komplette request-model til det valgte operator- eller self-service-endpoint.

Operatørressourcen inkluderer implementeringsadministrerede egenskaber såsom plantildeling, tilpasset domænebekræftelse, brugs- og betalingskonfiguration, valuta, moms, timepris og kundedata. Selvbetjeningsressourcen viser kun indstillinger, som tenant har tilladelse til at administrere.

Ændring af et brugerdefineret domæne gennem selvbetjening markerer domænet som ubekræftet, indtil den påkrævede bekræftelse er fuldført. Den valgte plan skal understøtte et tilpasset domæne. Brug operatøren API til at administrere bekræftelsestilstand; lad ikke en upålidelig tenant-klient hævde, at dens eget domæne er verificeret.

Slet en tenant

Sletning af en tenant er irreversibel og kaskaderende. Den sletter alle miljøer i tenant'en og alle applikationer, autentificeringsmetoder, brugere, sessioner, grants, nøgler og andre FoxIDs-data. Den fjerner også konfiguration på tenant-niveau og custom domain-routing. Master tenant kan ikke slettes. Logs, der allerede er sendt til et eksternt lager, er fortsat underlagt lagerets retention- og slettepolitik.

Før sletning skal du stoppe trafik, eksportere konfiguration eller data, der skal bevares, annullere eller afstemme ekstern fakturering, hvor det er relevant, og kontrollere tenantens tekniske navn. Kræv eksplicit bekræftelse i operatorværktøjer. Brug ikke tenantsletning til midlertidigt at deaktivere adgang; deaktiver eller opdater i stedet de relevante brugere, applikationer eller autentificeringsmetoder.

Automatisering og sikkerhedsvejledning

Foretræk selvbetjeningsendpoints, når en klient kun skal administrere sin egen tenant.
Begræns operatørlegitimationsoplysninger til en lille, pålidelig leveringstjeneste.
Hold det tekniske navn tenant stabilt, og gem det uafhængigt af visnings-, kunde- og brugerdefinerede domænedata.
Brug get-modify-put, så nye egenskaber ikke nulstilles af en ældre integration.
Brug paginering for tenantoversigter, og afstem efter teknisk navn.
Behandl oprettelse og sletning af tenants som langvarige, sammensatte administrationshandlinger; brug passende klienttimeouts, og verificer den endelige tilstand efter et afbrudt svar.
Forvent, at oprettelses-, opdaterings- og sletteanmodninger vises i Control-auditloggen. Læseoperationer skrives ikke som audithændelser.

Almindelige fejlsvar

400 Bad Request når tenant-, administrator-, plan-, betalings-, kunde- eller brugerdefinerede domænedata er ugyldige.
401 Unauthorized, når adgangstokenet mangler eller er ugyldigt.
403 Forbidden, når den, der ringer, mangler den nødvendige master- eller tenant-adgangsrettighed.
404 Not Found, når den valgte tenant ikke eksisterer.
409 Conflict, når der allerede findes et tenant-navn eller en anden unik værdi.

Brug svarteksten til valideringsdetaljer og Swagger UI til de svar, der er erklæret af hver handling.