Claude User Profiles and Inference Hooks: Setup and Governance
Learn how Anthropic user profiles isolate safety actions across end customers, how organization webhooks monitor bans, and how inference hooks run inline.
- On 2026-10-20, Anthropic launched user profiles to let gateways and platforms attribute API calls to distinct end customers.
- User profiles isolate safety classifiers so enforcement blocks apply to an individual customer rather than your whole organization.
- Inference hooks graduated from beta for Claude Enterprise, evaluating prompts and tool calls inline before inference begins.
- Admin API organization webhooks entered beta under the webhooks-2026-10-07 header to notify systems when customer profiles face restrictions.
What Changed on 2026-10-20 in the Anthropic Platform
The Claude platform release notes published on 2026-10-20 introduced three major additions targeting enterprise governance, platform providers, and API resellers. The core release introduces user profiles, which allow organizations running shared gateways or consumer products to associate each outbound API call with a distinct end customer. Previously, automated safety enforcement classifiers operated at the organization level, meaning a single customer violating terms could risk disruptions for an entire organization. Profiles confine enforcement penalties to the specific offending customer profile.
Simultaneously, inference hooks graduated out of beta for Claude Enterprise accounts. This architecture routes inference prompts and tool interactions to an external HTTPS AI security server operated by your team before model processing runs. Denial verdicts stop execution inline prior to generation. Alongside these systems, Anthropic introduced organization webhooks in beta for the Admin API under the webhooks-2026-10-07 header, dispatching real-time notifications when safety enforcement restricts or lifts restrictions on registered user profiles.
How User Profiles Protect Gateways and Platform Operators
When developers build software-as-a-service applications or API proxy gateways, every outgoing prompt sent to Anthropic normally shares the same organization credentials. Anthropic maintains automated classifiers that monitor live traffic to protect against abuse. If unsegmented traffic contains abusive inputs, enforcement actions—such as account holds or total blocks—affect the entire organization. By implementing user profiles, platforms supply an attribution layer so automated classifiers can isolate penalties to a single uprof_ identifier.
Profiles do not carry conversation logs and are non-billable, meaning registering profiles does not alter standard model pricing. When planning architecture, teams must separate internal company usage from customer-facing services by provisioning distinct organizations on the Claude API console. Workspaces inside a single organization share user profiles, so keeping internal tools separated from end-customer traffic requires distinct top-level organizations.
| Traffic Origin | Profile Registration | access_type Field | Enforcement Scope |
|---|---|---|---|
| Individual SaaS end user | One profile created at sign-up | application (default) | Individual user profile |
| Reseller / Gateway client company | One profile per client business | passthrough | Single customer company |
| Internal company tooling | No profile (separate organization) | Not applicable | Entire internal organization |
| Internal team workspaces | Inherits organization profiles | Not applicable | Shared across organization |
Registering Profiles and Attributing API Requests
User profiles are created by sending an HTTPS POST request to /v1/user_profiles with a standard Claude API key. The endpoint is not idempotent: submitting repeated requests creates distinct records even when submitting identical customer references. Platforms should store the returned uprof_ string in their local database alongside customer records during user onboarding. The official SDK and the ant CLI provide helper interfaces for creating profiles and passing attribution headers.
curl https://api.anthropic.com/v1/user_profiles \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"name": "Acme Analytics, Inc.",
"access_type": "passthrough",
"external_user_details": {
"reference_id": "cust-8f2a1c",
"country": "US"
}
}'
Every field under external_user_details is optional, including country (formatted as an ISO 3166-1 alpha-2 string), reference_id, entity_type (individual, business, non_profit, or government), and account_status (active, suspended, or blocked). Teams that cannot share raw identifiers can provide custom hashes via name_hash or email_hash using stable hashing routines. To link standard Messages, token counting, or batch requests to a customer, send the identifier inside the anthropic-user-profile-id header.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-user-profile-id: uprof_011CZkZCu8hGbp5mYRQgUmz9" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude"}
]
}'
Organization Webhooks and Handling Enforcement Events
Alongside user profiles, Anthropic deployed organization webhooks into the Admin API in beta. Access requires the webhooks-2026-10-07 beta header and coordination with an Anthropic account team. Once provisioned via the /v1/organizations/webhooks endpoint, the webhook engine monitors two distinct lifecycle events: one triggered whenever Anthropic restricts or bans a user profile, and another triggered when that restriction or ban expires or gets lifted.
If an end customer issues abusive prompts that trigger enforcement, their specific profile enters a restricted state. Because outgoing requests validate the anthropic-user-profile-id header against the organization, requests carrying an invalid or unowned profile identifier return an HTTP 400 status with invalid_request_error. Message Batches behave slightly differently: batch creation validates ID formatting, and requests containing unowned profile identifiers fail later with an errored result state. Integrating organization webhooks allows platforms to automatically disable upstream billing, flag internal support tickets, or inform customers of safety violations without discovering blocks through failed production inferences.
Inline Governance with Claude Enterprise Inference Hooks
While user profiles protect platforms against blanket safety bans, inference hooks provide proactive inline data controls for Claude Enterprise organizations. Configuring inference hooks requires the organization:manage permission held by Owner or Primary owner roles. Once enabled, the Anthropic gateway pauses user requests across web apps, Claude Desktop, Claude Code, Cowork, and Claude Tag, dispatching an HTTPS POST payload containing the conversation transcript to an external AI security server.
The inspection mechanism fires during two specific lifecycle hooks: the prompt event before generation begins, and the tool_call event if an organization enables Validate tool calls. Requests conform to the Standard Webhooks signature specification so the inspection receiver can verify origin integrity. The security server must respond within a configured verdict timeout, which defaults to 5 seconds. If the security server answers with {"action": "allow"}, the request proceeds to the model. If it answers with deny, Anthropic rejects the interaction before token generation begins, presenting the user with the custom reason passed in deny_reason alongside standing administrative instructions.
| Capability | Inference Hooks | Compliance API |
|---|---|---|
| Execution Timing | Inline, prior to model generation | Asynchronous, after interaction completes |
| Communication Flow | Anthropic pushes HTTPS requests to your server | Customer queries Anthropic endpoints |
| Operational Scope | Evaluates and blocks prompts or tool calls | Exports logs, chats, and audit archives |
| Allowed Verdicts | allow or deny actions | Read-only query responses |
Inference hooks transmit text transcripts and extracted attachment text, but raw binary image bytes and internal system prompts are never sent. If an AI security endpoint times out or errors, an organization’s fallback policy determines whether requests pass unchecked or stop completely. Sustained service failures trip an automated circuit breaker, halting outbound webhook inspection until the server recovers.
Implementation and Migration Checklist
Before rolling out profiles or inference hooks into production systems, engineering teams should verify system constraints and operational requirements:
- Segregate environments: Run internal team prompts in a separate Claude API organization from external customer traffic to isolate policy scopes.
- Choose access types: Assign access_type application for individual consumers and passthrough when reselling access to third-party companies.
- Cache profile IDs: Store the uprof_ identifier returned by POST /v1/user_profiles locally during customer onboarding to avoid duplicate non-idempotent records.
- Attach attribution headers: Ensure all Messages, batch runs, and token counting calls pass anthropic-user-profile-id.
- Handle error codes: Catch HTTP 400 invalid_request_error responses generated when profile identifiers do not match the calling organization.
- Subscribe to Admin webhooks: Request access via your account team to register endpoints under webhooks-2026-10-07 for ban and restriction alerts.
- Plan hook recovery: When deploying enterprise inference hooks, configure timeout budgets (5 seconds default) and establish conversational recovery steps such as Claude Code /rewind.