Anthropic User Profiles: isolate safety enforcement by customer

Anthropic's new User Profiles feature gives platforms, AI gateways and Claude resellers a provider-side identity for each end customer. When that profile ID is attached to Messages, Message Batches or token-counting requests, Anthropic says a safety enforcement action can apply to the represented customer instead of the whole API organization. Organization Webhooks can then notify your control plane when a profile becomes restricted or banned and when the action ends. The production design still needs a stable internal mapping, minimal personal data, signed and idempotent webhook processing, a reconciliation job and application-level authorization.

Anthropic announced the features on 20 October 2026. User Profiles appear in the beta API reference under /v1/user_profiles. Organization Webhooks are a separate beta capability using the webhooks-2026-10-07 header and require account-team access. The documented behavior below is separated from the engineering recommendations for a tenant-aware control plane.

What changed, and why SaaS platforms should care

Before a provider can isolate an enforcement action, it needs a durable subject to which the action applies. Anthropic documents a User Profile as a record representing either an individual end user of an application or a company receiving resold Claude access. A request can send the returned uprof_ identifier in the anthropic-user-profile-id header.

The distinction is operationally important for multi-tenant products. If every customer shares one anonymous upstream credential, the provider sees organization-level traffic without a product-level boundary. User Profiles add an attribution boundary. They do not replace your tenant ID, authentication, billing account, abuse controls or audit log; they complement those controls with a provider-recognized subject.

Anthropic's release note says this allows a safety action to target one end customer instead of the entire organization. Treat that as a documented platform capability, not a guarantee that every incident will be isolated or that no organization-wide action can occur. Your service must still plan for upstream account suspension, regional failure, rate limiting and other organization-level conditions.

Choose the profile boundary deliberately

Use access_type application when one profile represents an individual end user of your product. Use passthrough when the profile represents a company to which you resell Claude access. Do not create one profile per browser session, API key or conversation: those identifiers rotate too often and fragment the enforcement history. Do not reuse one profile across unrelated tenants merely because they share an email domain.

A practical mapping table is tenant-scoped and immutable:

ai_subject(
  tenant_id,
  internal_subject_id,
  anthropic_profile_id,
  access_type,
  lifecycle_state,
  last_synced_at,
  UNIQUE(tenant_id, internal_subject_id),
  UNIQUE(anthropic_profile_id)
)

Create the profile once through a durable provisioning job, persist the returned ID, and reuse it for later requests. If creation times out after the provider may have accepted it, search or list before retrying blindly. The reference says the legacy external_id is not enforced unique, so it should not be treated as the database constraint that prevents duplicates.

Choose the subject at the same layer that authorizes the request. A consumer chat product normally maps the signed-in user. A company-level gateway using passthrough normally maps the customer account. A support tool serving many merchants might need both an internal user and an upstream company profile; the upstream profile does not remove the need to authorize the employee against the merchant locally.

Minimize data and keep identity claims honest

The API accepts optional name, metadata and external-user details. Anthropic states that the platform supplies those external details and Anthropic does not verify them. Do not describe a profile as verified identity unless your own identity process supports that claim.

Store only what the operational contract needs. Prefer an opaque reference generated for the integration over a raw database primary key that leaks internal structure. Avoid putting email addresses, names, access tokens, case notes or prompt excerpts in metadata. Anthropic's CMEK documentation says User Profile name, external_id and metadata are stored under Anthropic-managed encryption rather than the customer's key and explicitly warns against sensitive personal data in metadata.

If you send a hash such as email_hash, define its canonicalization, keying, rotation and purpose. An unsalted hash of a common email is still guessable. A keyed HMAC under a dedicated secret is safer for equality matching, but it remains personal data in many governance contexts. Record the lawful purpose and retention period instead of assuming hashing makes the field anonymous.

Keep lifecycle states separate. Your application may suspend a user for unpaid billing while Anthropic reports the profile unrestricted; those are different decisions. Model local account status, local safety decision and upstream enforcement status as separate fields, then compute a conservative admission decision from all three.

Attach the profile before every supported request

The mapping matters only if the correct profile ID reaches the API call. Put profile resolution in the central gateway or SDK wrapper used by Messages, Message Batches and token counting. Reject a request when the authenticated tenant and the mapped profile do not match. Never accept anthropic-user-profile-id directly from an untrusted client.

Propagate an internal request ID and record the profile ID, tenant ID, route, model and outcome in an access-controlled audit event. Do not copy prompts into general logs. An example gateway contract is:

authorize(session, tenant, capability)
profile = resolve_profile(tenant.id, session.subject_id)
assert profile.lifecycle_state == "active"
assert current_upstream_status(profile.id) allows request

response = anthropic.messages.create(
  headers = {"anthropic-user-profile-id": profile.id},
  body = validated_request
)
record_request_outcome(request_id, tenant.id, profile.id, response.status)

Run contract tests that fail if a supported route omits the profile header or attaches the wrong tenant's profile. Test batch and token-counting paths separately; a gateway that tags only interactive Messages leaves an attribution gap.

Process Organization Webhooks as hints to read current state

Organization Webhooks deliver two event types: user_profile.enforcement_action_opened and user_profile.enforcement_action_resolved. The event carries a profile ID and an enforcement-action ID, not the full action. Anthropic instructs consumers to retrieve the current profile because events can arrive late or out of order. The profile's enforcement_status summarizes open actions as banned, restricted or unrestricted; any unknown value should be treated as restricted.

Verify the Standard Webhooks signature over the original body using the endpoint signing secret. Check timestamp freshness, store the event ID under a unique constraint, return 2xx within five seconds and perform retrieval asynchronously. The documentation says duplicates can occur with the same event ID, failed delivery is retried only a few times, and an endpoint can be disabled after repeated failures.

A safe receiver therefore does very little synchronously:

1. read the raw body and signature headers; 2. verify signature and timestamp before parsing trusted fields; 3. insert the event ID idempotently; 4. enqueue a profile-refresh job; 5. return 204; 6. retrieve the current profile and update the local projection transactionally.

Do not unblock a customer merely because a resolved event arrived. Fetch the profile first: another action may still be open, or a newer event may already have changed the state. Likewise, a 404 means the profile was deleted and needs an explicit local policy, not an automatic unrestricted state.

Reconcile because webhook delivery is not a ledger

Anthropic documents several gaps: events that opened before registration are not replayed, failed events can be dropped after limited retries, disabled endpoints skip events without later backfill, and deleting a profile ends open actions without a resolved event. A webhook-only state machine will therefore drift.

Run a periodic reconciliation job that lists profiles filtered by restricted and banned status and follows next_page until it is null. The documentation warns that a page can contain fewer profiles than the requested limit, or even none, before the list ends. Never stop because one page is short or empty. Compare the authoritative result with the local projection, repair differences and alert on unexplained missing profiles.

Also monitor endpoint state, signature failures, duplicate rate, profile-refresh latency, reconciliation drift and the age of the last successful full scan. Store the signing secret in a secret manager. When rotating it, deploy the new receiver configuration immediately because Anthropic says the old secret stops working at once and retries of earlier events use the new secret.

The reliable webhook processing guide covers the inbox and retry pattern in more detail. The Anthropic Compliance API audit guide is a separate control: Compliance data supports audit and review, while User Profiles and enforcement webhooks control request attribution and current admission state.

Define restriction behavior before an incident

A restriction and a ban should not be translated into ad hoc UI errors. Define a policy matrix for each status and product route. A ban may block all new model requests for that profile. A restriction may allow only routes that Anthropic still accepts; your gateway should respect the actual upstream response rather than guess what the restriction permits.

Keep irreversible application actions outside the model. An upstream safety status can stop access, trigger review or narrow capabilities, but it should not automatically delete customer data, terminate a paid account or notify third parties without an approved business process. Preserve an appeal or support path appropriate to your terms and jurisdiction.

Test the control plane with synthetic profiles: duplicate opened events, resolved-before-opened delivery, a profile with two simultaneous actions, event loss followed by reconciliation, a disabled endpoint, secret rotation during retry, profile deletion and an upstream outage. The desired property is not perfect event order; it is convergence to the provider's current state without crossing tenant boundaries.

When not to use this feature as your identity system

User Profiles are useful when a platform sends Claude traffic for multiple end customers and wants provider-side attribution and scoped enforcement. They are unnecessary for a single internal service account with no end-customer boundary. They are also not a replacement for OIDC, session management, RBAC, consent, billing or a customer directory.

Organization Webhooks are currently beta, require enablement, and are unavailable under some documented configurations, including HIPAA-ready organizations. If your product requires a safety state feed but cannot use the webhook feature, build a documented polling and error-response strategy instead of claiming real-time coverage.

The implementation contract is straightforward: choose one stable subject boundary, create and persist the provider profile, attach it centrally to every supported request, minimize identity data, verify and deduplicate webhook events, retrieve current state rather than trusting event order, and reconcile the full restricted set on a schedule. That architecture uses Anthropic's new isolation boundary without confusing it with the identity and authorization controls your product still owns.

Prepared by: Noor Yasser