Control API - environments

Use the FoxIDs Control API to list, create, configure, and delete environments in a tenant. An environment is called a track in Control API routes and schemas.

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

Endpoint base

Environment administration is performed through the tenant's master environment. The examples use FoxIDs Cloud:

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

Replace {tenant_name} with the tenant's technical name. Change the host for a self-hosted deployment. Send the Control API access token in the Authorization: Bearer {access_token} header.

Environment operations require the corresponding tenant or environment access right. The environments returned by list operations are limited to those the caller can access. Use the Control API access-right hierarchy to grant only the required read, create, update, or delete operation.

Environment operations

Environment operations are grouped under tenant tracks in Swagger.

Operation Endpoint Purpose
List GET /!tracks List accessible environments with optional filtering and pagination.
Get GET /!track?name={name} Get the complete configuration for one environment.
Create POST /!track Create an environment and its default Login authentication method.
Update PUT /!track Replace the editable environment configuration.
Delete DELETE /!track?name={name} Permanently delete an environment and its data.

Append each endpoint to the endpoint base.

List and identify environments

GET /!tracks accepts filterName and paginationToken. The filter matches either the technical name or the displayName, without regard to case.

The response contains a data collection and an opaque paginationToken. To read the next page, repeat the same request with the returned token and the same filter. Continue until the response no longer contains a token. Do not interpret or modify the token.

The technical name identifies the environment in Control API URLs and in subsequent get, update, and delete operations. Treat it as a stable automation key. Use displayName for text presented to administrators.

Create an environment

Environment names are lower-case. Supply a name when an integration requires a predictable URL, or omit it and let FoxIDs generate a unique name. A request must contain either a name or a display name.

Creating an environment also creates the default Login authentication method. Other applications, authentication methods, users, keys, and environment resources are configured separately after creation.

The tenant plan can limit the number of environments. A create request can therefore fail when the limit is reached. Concurrent plan-limited create operations can return 423 Locked; retry after a short delay.

Update environment settings

PUT /!track is a full update, not a patch. First get the current environment, preserve all properties that should remain unchanged, apply the intended changes, and send the complete editable representation.

The technical name selects the environment and is not renamed by an update. Editable settings include the display and company details, sequence lifetime, claim mapping behaviour, login-failure protection, password policies, external password and directory integration, and permitted iframe domains. Some related resources, including SMS, email, claim mappings, texts, keys, and certificates, have dedicated endpoints and are not replaced through the environment operation.

Updated settings are used by subsequent requests after FoxIDs invalidates the environment configuration cache.

Delete an environment

Deleting an environment is an irreversible, cascading operation. It removes the environment configuration and all data scoped to that environment, including its applications, authentication methods, users, sessions, grants, keys, and other resources. Links from other environments to the deleted environment are also removed.

Do not use environment deletion as a way to clear selected resources. Delete or update those resources individually when the environment must remain available. Before deleting an environment, stop traffic to it, export any configuration or data that must be retained, and verify the technical name in the request.

Automation guidance

  • Keep technical names stable and store them separately from display names.
  • Use list pagination even when a tenant currently has only a few environments.
  • Use a get-modify-put workflow to avoid unintentionally resetting settings added in a newer FoxIDs version.
  • Create dependent resources only after the environment create request succeeds.
  • Treat delete as a permanent teardown operation and require an explicit confirmation in administrative tooling.
  • 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 the environment data or name is invalid, a reserved name is used, or a plan limit is reached.
  • 401 Unauthorized when the access token is missing or invalid.
  • 403 Forbidden when the caller lacks the required access right.
  • 404 Not Found when the selected environment does not exist.
  • 409 Conflict when an environment with the same technical name already exists.
  • 423 Locked when a plan-limited create operation is temporarily locked.

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