End User APIs
Manage the effective user’s location, locale, default generation preferences and metadata. There is no arbitrary target-user field in these request bodies. Authorized backend calls can act on behalf of a user.
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
Related guide: Manage end-user profiles
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Authentication
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: Bearer Auth
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
The end user this call acts for. Required with an sk_… key, because a secret
key identifies your tenant and not a user; omitting it returns
401 authenticated user_id is required. The key needs the users:impersonate
scope or the call fails with 403 insufficient_scope.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-On-Behalf-Of |
The end user's own JWT, issued by the OIDC provider configured on the
publishable key. Required alongside a pk_… key, and supplies the user
identity in place of X-On-Behalf-Of.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |
📄️ End users overview
Manage the effective user’s location, locale, default generation preferences and metadata. There is no arbitrary target-user field in these request bodies. Authorized backend calls can act on behalf of a user.
📄️ Authentication
overview}
🗃️ Endpoints
4 items
🗃️ Models
2 items
Document ID: DOC-CP-identity-access-api-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-CP-identity-access-api-overview#overview |
| JSON conventions | DOC-CP-identity-access-api-overview#json-conventions |
| Authentication | DOC-CP-identity-access-api-overview#authentication |