Control API - applications and authentication methods

Use the FoxIDs Control API to configure the applications that trust FoxIDs and the authentication methods FoxIDs trusts. In Control API routes and schemas, an application registration is called a downparty and an authentication method is called an upparty.

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

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint base and access rights

The examples use FoxIDs Cloud:

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

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

These operations require a party access right for the target environment. Grant only the required read, create, update, or delete operation through the Control API access-right hierarchy.

List and identify registrations

Use these endpoints to discover registrations before calling a type-specific endpoint:

The list responses contain safe summaries, the registration type, and an opaque pagination token. Use the type-specific get operation for the complete editable representation. Repeat a paginated request with the same filters and the returned token until no token is returned.

The technical name is the stable identifier used by get, update, delete, secret, key, and relationship operations. Names are lower-case. Supply a name on create when an integration requires a predictable identifier, or let FoxIDs generate one. Use the !newpartyname helper when a unique name is needed before a resource is created.

Type-specific operations

Each resource type has its own endpoint because the protocol configuration differs. The principal endpoints are:

The usual operations are GET ?name={name}, POST to create, PUT to update, and DELETE ?name={name}. Append the endpoint to the endpoint base. Consult Swagger for the operations supported by each type.

Creating applications or authentication methods is subject to the environment and tenant plan limits. Some concurrent plan-limited create operations can return 423 Locked; retry after a short delay.

Update and rename safely

Party PUT operations are full updates, not patches. Use this workflow:

1. List the resources or get the known resource by technical name.
2. Get its complete type-specific representation.
3. Preserve properties that should remain unchanged and apply the intended changes.
4. Send the complete editable representation to the matching type-specific PUT endpoint.

Use newName when the technical name must change. References are updated as part of the rename flow. The default Login authentication method named login cannot be renamed or deleted.

Client secrets, client keys, and some external API secrets are managed by dedicated endpoints. They are deliberately not returned as plaintext in the general party representation and should not be copied into a normal update request.

Connect applications to authentication methods

An application's allowUpParties collection controls which authentication methods can be used to sign in to that application. The referenced authentication methods must exist in the same environment and be compatible with the configuration.

Treat this relationship as part of the application's complete configuration when updating it. Deleting an authentication method can change sign-in routing for applications that reference it; verify dependent applications before deletion. Use an Environment Link when the authentication method or application is intentionally connected across FoxIDs environments.

Manage secrets and keys

OAuth 2.0 and OpenID Connect applications provide dedicated client-secret operations. A secret is accepted when created, stored as a hash, and not returned in plaintext. The list response contains the identifiers and safe information needed to manage existing secrets.

Use overlapping credentials for rotation:

1. Generate a new client secret and store it securely.
2. Create the client secret in FoxIDs and deploy the same value to the consuming application.
3. Verify that the application uses the new secret.
4. Delete the old secret by its application and secret identifiers.

OpenID Connect and OAuth 2.0 authentication methods can use dedicated client-secret or client-key operations, depending on the selected client authentication method. A private-key operation accepts certificate and private-key material. External Login has a dedicated secret endpoint. Use the exact endpoint and request schema shown in Swagger for the selected registration type.

Secrets, private keys, and complete certificate payloads are sensitive. Use TLS, grant access only to trusted automation clients, protect values at rest, and do not log request or response bodies.

Metadata and discovery helpers

Protocol helper operations reduce manual configuration but do not replace validation of the resulting resource:

• OpenID Connect and OAuth 2.0 authentication methods can read discovery metadata and populate compatible settings.
• SAML 2.0 application registrations and authentication methods can read metadata.
• WS-Federation application registrations and authentication methods can read metadata.
• WS-Federation authentication methods include a Microsoft Entra ID synchronisation helper.

After using a helper, inspect the returned configuration, apply local policy and claim settings, and save it through the type-specific create or update endpoint. Metadata can change over time, so define whether synchronisation is an explicit administrative action or a controlled recurring process.

Delete and dependency effects

Deleting an application stops new protocol requests for that application. Deleting an authentication method can prevent applications from completing sign-in and can alter Home Realm Discovery choices. Remove or update dependencies first, and treat both operations as permanent configuration changes.

Create, update, secret/key, helper, and delete requests are included in the Control audit log. Read operations are not written as audit events.

Common error responses

• 400 Bad Request when protocol settings, references, metadata, secrets, keys, or names are invalid, or a plan limit is reached.
• 401 Unauthorized when the access token is missing or invalid.
• 403 Forbidden when the caller lacks the required party access right.
• 404 Not Found when the selected registration, secret, or key does not exist.
• 409 Conflict when a technical name or secret identifier 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.

Related documentation

• Control API authentication and access rights
• Applications
• Authentication methods
• Environment Link
• Claims and claim transforms