Control API - tenant administratie

FoxIDs heeft afzonderlijke Control API-oppervlakken voor implementatieoperators die tenants beheren en voor een tenant die zijn eigen account beheert. Gebruik de operatorbewerkingen voor tenant-provisioning en cross-tenant-beheer. Gebruik de selfservice-bewerkingen wanneer een integratie beperkt moet blijven tot zijn eigen tenant.

Voordat u deze bewerkingen uitvoert, configureert u Control API authenticatie en toegangsrechten. Swagger blijft de exacte referentie voor tenant eigendommen, abonnements- en betalingsopties, validatieregels en antwoordschema's:

API oppervlakken

Implementatie-operator

Operatorbewerkingen worden aangeroepen in de master tenant:

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

Operatie	Eindpunt	Doel
Lijst	`GET /!tenants`	Vermeld niet-master tenants met optionele filters en paginering.
Krijgen	`GET /!tenant?name={name}`	Lees de beheerbron van iemand tenant.
Creëren	`POST /!tenant`	Richt een tenant, initiële beheerder en standaardbronnen in.
Update	`PUT /!tenant`	Vervang de bewerkbare, door de operator beheerde tenant-eigenschappen.
Verwijderen	`DELETE /!tenant?name={name}`	Verwijder definitief een tenant en alle tenant-gegevens.

Voor deze bewerkingen zijn master-tenant toegangsrechten vereist. Ze zijn bedoeld voor vertrouwd implementatiebeheer en SaaS provisioningservices.

Tenant zelfbediening

Een tenant roept zijn eigen bewerkingen aan via zijn master-omgeving:

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

Operatie	Eindpunt	Doel
Krijgen	`GET /!mytenant`	Lees het tenant-account en de beschikbare instellingen van de beller.
Update	`PUT /!mytenant`	Toegestane selfservice-eigenschappen bijwerken.
Verwijderen	`DELETE /!mytenant`	Verwijder definitief de tenant-gegevens van de beller en alle gegevens van tenant.

Selfservice gebruikt toegangsrechten voor tenant en kan geen andere tenant beheren. Planwijzigingen, betalingsinstellingen en aangepaste domeinen zijn ook onderworpen aan het geconfigureerde beleid van de implementatie.

Wijzig de host in deze voorbeelden voor een zelf-hostende implementatie en verzend het toegangstoken in de header Authorization: Bearer {access_token}.

Lijst en identificeer tenants

GET /!tenants accepteert filterName, filterCustomDomain en paginationToken. Als beide filters zijn opgegeven, wordt een tenant geretourneerd als de naam of het aangepaste domein overeenkomt. De records master tenant en alleen voor intern gebruik tenant zijn niet inbegrepen.

Herhaal een gepagineerd verzoek met dezelfde filters en het geretourneerde ondoorzichtige token totdat er geen token wordt geretourneerd. Interpreteer of wijzig het token niet.

De kleine letter tenant name is de stabiele ID die wordt gebruikt in de URL's FoxIDs en Control API. Behandel het als een onveranderlijke automatiseringssleutel. Een aangepast domein is een afzonderlijke routing- en brandingeigenschap en mag niet worden gebruikt als de naam van de Control API route tenant.

Een tenant inrichten

Het maken van Tenant is een samengestelde inrichtingsbewerking. Een succesvol verzoek creëert:

het tenant-record;
de master-omgeving van de tenant en de standaard inlogverificatiemethode;
de initiële beheerdergebruiker;
de Control API resource- en Control Client-applicatie;
de geconfigureerde standaardomgevingen van de implementatie.

De initiële beheerder kan een opgegeven wachtwoord ontvangen of een wachtwoord instellen via de geconfigureerde e-mailstroom. Bescherm elk opgegeven wachtwoord en log de verzoektekst niet.

De aanvraag kan ook een plan selecteren en klant-, claims- en aangepaste domeininstellingen initialiseren waar de implementatie dit toestaat. De uniekheid van de naam, planregels, ondersteuning voor aangepaste domeinen en vereiste beheerdersgegevens worden gevalideerd voordat de inrichting wordt voltooid. Als een account- of gegevensfout de inrichting onderbreekt, probeert FoxIDs de bronnen op te ruimen die door dat verzoek zijn gemaakt; niettemin moeten clients elke fout als mislukt beschouwen en de status verifiëren voordat ze het opnieuw proberen met dezelfde tenant-naam.

Update de tenant-instellingen

Tenant PUT-bewerkingen zijn volledige updates, geen patches. Haal de huidige resource op, behoud alle bewerkbare eigenschappen die ongewijzigd moeten blijven, pas de beoogde wijziging toe en verzend het volledige aanvraagmodel voor de geselecteerde operator of het selfservice-eindpunt.

De operatorresource omvat door implementatie beheerde eigenschappen zoals plantoewijzing, aangepaste domeinverificatie, gebruiks- en betalingsconfiguratie, valuta, btw, uurprijs en klantgegevens. De selfservicebron geeft alleen instellingen weer die de tenant mag beheren.

Als u een aangepast domein via selfservice wijzigt, wordt het domein als niet-geverifieerd gemarkeerd totdat de vereiste verificatie is voltooid. Het geselecteerde abonnement moet een aangepast domein ondersteunen. Gebruik de operator API om de verificatiestatus te beheren; laat een niet-vertrouwde tenant-client niet beweren dat zijn eigen domein is geverifieerd.

Verwijder een tenant

Het verwijderen van Tenant is onomkeerbaar en trapsgewijs. Het verwijdert elke omgeving in de tenant en alle beoogde applicaties, authenticatiemethoden, gebruikers, sessies, subsidies, sleutels en andere FoxIDs-gegevens. Het verwijdert ook de configuratie op tenant-niveau en de routering naar aangepaste domeinen. De master tenant kan niet worden verwijderd. Logboeken die al naar een externe opslagplaats zijn verzonden, blijven onderworpen aan het bewaar- en verwijderingsbeleid van die opslagplaats.

Stop vóór het verwijderen het verkeer, exporteer de configuratie of gegevens die moeten worden bewaard, annuleer of stem externe facturering af waar van toepassing, en verifieer de technische naam van de tenant. Vereist expliciete bevestiging in de operatortools. Gebruik het verwijderen van tenant niet om de toegang tijdelijk uit te schakelen; schakel in plaats daarvan de relevante gebruikers, applicaties of authenticatiemethoden uit of update deze.

Automatisering en beveiligingsbegeleiding

Geef de voorkeur aan selfservice-eindpunten wanneer een client alleen zijn eigen tenant hoeft te beheren.
Beperk de inloggegevens van de operator tot een kleine, vertrouwde inrichtingsservice.
Houd de technische naam van tenant stabiel en sla deze onafhankelijk van display-, klant- en aangepaste domeingegevens op.
Gebruik get-modify-put zodat nieuwe eigenschappen niet worden gereset door een oudere integratie.
Gebruik paginering voor tenant inventarissen en stem af op technische naam.
Behandel het maken en verwijderen van tenant als langlopende samengestelde beheeracties; gebruik de juiste clienttime-outs en verifieer de eindstatus na een onderbroken reactie.
Verwacht dat aanvragen voor het maken, bijwerken en verwijderen verschijnen in het controle-auditlogboek. Leesbewerkingen worden niet geschreven als auditgebeurtenissen.

Veelvoorkomende foutreacties

400 Bad Request wanneer tenant-, beheerders-, abonnements-, betalings-, klant- of aangepaste domeingegevens ongeldig zijn.
401 Unauthorized wanneer het toegangstoken ontbreekt of ongeldig is.
403 Forbidden wanneer de beller niet over de vereiste toegangsrechten voor master of tenant beschikt.
404 Not Found wanneer de geselecteerde tenant niet bestaat.
409 Conflict wanneer er al een tenant-naam of een andere unieke waarde bestaat.

Gebruik de antwoordtekst voor validatiedetails en Swagger UI voor de antwoorden die door elke bewerking zijn gedeclareerd.