# Manage downstream customers

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

## Before you begin {#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 {#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}

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](/docs/credentials/reference/http-api#credential-collection)). 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 {#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 {#next-steps}

Read [Channel Auth Providers](/docs/channels/auth-providers.md), [Scoped bindings](/docs/credentials/scoped-bindings), and [Policies](/docs/policies.md) before serving shared Agents to downstream customers.