Documentation / Platform API / Administration

Manage downstream customers

Provision customer identities, map external organization evidence, and bind customer-specific Policies within a parent tenant.

Before you begin

Use customer tenancy only for downstream organizations served by a parent tenant. Choose an opaque Constal customer id and identify the Auth Provider’s stable external organization id. Prepare a deployed Policy owned by the authenticated parent tenant. Customer tenants do not own deployments, Credentials, billing administrators, or platform operators.

Steps

  1. List customers with GET /v1/customers or inspect one through GET /v1/customers/:customerId.
  2. Create or update idempotently with PUT /v1/customers/:customerId. Include a stable eventId and the documented customer metadata. The platform checks customer:create or customer:update against current existence.
  3. Enable or disable through POST /v1/customers/:customerId/enable or /disable, again with a stable eventId.
  4. Map one Auth Provider namespace/external identity key through PUT /v1/customers/:customerId/identity-mappings/:mappingId. Delete that exact mapping with DELETE and an event body when it should no longer authenticate as this customer.
  5. Bind an ordinary deployed parent-tenant Policy through PUT /v1/customers/:customerId/policy-bindings/:bindingId. Delete the exact binding to remove it. Cross-tenant or undeployed Policy CRNs are rejected.
  6. Configure the Channel manifest’s customer identity mode as required or optional. The Auth Provider returns { customer: { externalId } }; central auth resolves that evidence to the opaque customer CRN and Policy set. With optional, an external id that is not mapped to a Customer is received unaffiliated, and the Channel's Policy for unaffiliated Principals decides it. An id whose Customer is disabled, or whose Customer has no Policies bound in the namespace, is refused, as is any unresolved id with required.

Return origins

Return origins are the https origins a browser may be returned to after a Credential interaction started with a returnUrl (see the Credential HTTP API). They are a tenant setting. The callback checks them again when it returns the browser, so an origin removed while an interaction was open is not returned to: the browser lands on the Console Credential page instead.

  • GET /v1/return-origins requires return-origin:read and answers { "data": ["https://app.example.com"] }.
  • PUT /v1/return-origins requires return-origin:update and replaces the whole list with { "eventId": "...", "origins": ["https://app.example.com"] }. Each entry is an exact origin with no path, query, or credentials. It answers { "origins": [...] }.

Tenant owners and admins hold both scopes.

Verify

Invoke the same customer-aware Channel using two external customer identities and the same public session id. Confirm each accepted Run has the expected customer CRN, Policy snapshot, scoped Resource/Credential assignments, and isolated session history. Disable one customer and verify new admission fails without affecting the other.

Next steps

Read Channel Auth Providers, Scoped bindings, and Policies before serving shared Agents to downstream customers.