Control API - tenant administration

FoxIDs has separate Control API surfaces for deployment operators that administer tenants and for a tenant that administers its own account. Use the operator operations for tenant provisioning and cross-tenant administration. Use the self-service operations when an integration should be confined to its own tenant.

Before calling these operations, configure Control API authentication and access rights. Swagger remains the exact reference for tenant properties, plan and payment options, validation rules, and response schemas:

• Swagger (OpenAPI) JSON
• Swagger UI

API surfaces

Deployment operator

Operator operations are called in the master tenant:

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

These operations require master-tenant access rights. They are intended for trusted deployment administration and SaaS provisioning services.

Tenant self-service

A tenant calls its own operations through its master environment:

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

Self-service uses tenant access rights and cannot administer another tenant. Plan changes, payment settings, and custom domains are also subject to the deployment's configured policies.

Change the host in these examples for a self-hosted deployment, and send the access token in the Authorization: Bearer {access_token} header.

List and identify tenants

GET /!tenants accepts filterName, filterCustomDomain, and paginationToken. When both filters are provided, a tenant is returned when either its name or custom domain matches. The master tenant and internal usage-only tenant records are not included.

Repeat a paginated request with the same filters and the returned opaque token until no token is returned. Do not interpret or modify the token.

The lower-case tenant name is the stable identifier used in FoxIDs and Control API URLs. Treat it as an immutable automation key. A custom domain is a separate routing and branding property and must not be used as the Control API route tenant name.

Provision a tenant

Tenant creation is a compound provisioning operation. A successful request creates:

• the tenant record;
• the tenant's master environment and its default Login authentication method;
• the initial administrator user;
• the Control API resource and Control Client application;
• the deployment's configured default environments.

The initial administrator can receive a supplied password or establish a password through the configured email flow. Protect any supplied password, and do not log the request body.

The request can also select a plan and initialise customer, claims, and custom-domain settings where the deployment permits them. Tenant name uniqueness, plan rules, custom-domain support, and required administrator data are validated before provisioning completes. If an account or data error interrupts provisioning, FoxIDs attempts to clean up resources created by that request; nevertheless, clients should treat any failure as unsuccessful and verify state before retrying with the same tenant name.

Update tenant settings

Tenant PUT operations are full updates, not patches. Get the current resource, preserve all editable properties that should remain unchanged, apply the intended change, and send the complete request model for the selected operator or self-service endpoint.

The operator resource includes deployment-managed properties such as plan assignment, custom-domain verification, usage and payment configuration, currency, VAT, hourly price, and customer data. The self-service resource exposes only settings the tenant is permitted to manage.

Changing a custom domain through self-service marks the domain as unverified until the required verification completes. The selected plan must support a custom domain. Use the operator API to manage verification state; do not let an untrusted tenant client assert that its own domain is verified.

Delete a tenant

Tenant deletion is irreversible and cascading. It deletes every environment in the tenant and all scoped applications, authentication methods, users, sessions, grants, keys, and other FoxIDs data. It also removes tenant-level configuration and custom-domain routing. The master tenant cannot be deleted. Logs already sent to an external repository remain subject to that repository's retention and deletion policy.

Before deletion, stop traffic, export configuration or data that must be retained, cancel or reconcile external billing where applicable, and verify the tenant's technical name. Require explicit confirmation in operator tooling. Do not use tenant deletion to disable access temporarily; disable or update the relevant users, applications, or authentication methods instead.

Automation and security guidance

• Prefer self-service endpoints when a client only needs to manage its own tenant.
• Restrict operator credentials to a small, trusted provisioning service.
• Keep the tenant technical name stable and store it independently of display, customer, and custom-domain data.
• Use get-modify-put so new properties are not reset by an older integration.
• Use pagination for tenant inventories and reconcile by technical name.
• Treat tenant creation and deletion as long-running compound administration actions; use appropriate client timeouts and verify the final state after an interrupted response.
• Expect create, update, and delete requests to appear in the Control audit log. Read operations are not written as audit events.

Common error responses

• 400 Bad Request when tenant, administrator, plan, payment, customer, or custom-domain data is invalid.
• 401 Unauthorized when the access token is missing or invalid.
• 403 Forbidden when the caller lacks the required master or tenant access right.
• 404 Not Found when the selected tenant does not exist.
• 409 Conflict when a tenant name or another unique value already exists.

Use the response body for validation details and Swagger UI for the responses declared by each operation.

Related documentation

• Control API authentication and access rights
• FoxIDs Control overview
• Environment API
• Plans
• Custom domains