Identity#

Identity answers who is making a call. Humans and machines are distinct actor types with distinct lifecycles — not one resource with a flag — so the same enterprise can mix human operators, automations, and federated identities without collapsing them into one opaque "user". What an actor is allowed to do lives in Access.

Actor Types#

Two first-class actor types are exposed in the public API:

• Human actor — a real person; can be platform-hosted or federated through an external identity provider
• Service principal — a non-human caller (integration, automation, service account)

How Human Actors Are Sourced#

Two ways of bringing humans into an enterprise:

• Platform-hosted users — identity lives on the platform; the enterprise creates and manages them through the public API.
• Federated users — identity lives in a partner IdP. The platform trusts identity assertions from configured providers and JIT-provisions a regular users/{id} record on first successful federated auth. Subsequent logins reuse it.

Both are first-class human actors in the same model — same role assignments, same approval cases, same governance flows. The difference is only where the identity is sourced and where authentication happens.

Acting On Behalf Of A Human#

A backend-to-backend integration does not mean every call is made as a service account. Many actions require a real human actor of record — to preserve attribution, satisfy four-eyes rules, keep approval cases meaningful, and keep the audit trail human-anchored.

The platform supports this through standard token exchange (RFC 8693): a service integration presents a federated human's identity assertion and obtains a platform access token whose effective actor is that human, scoped by the human's role assignments — not the service account's.

The integration code is the same as a regular machine call; what changes is who the platform records as the actor of record and which authorization rules apply. A service credential carries human intent into the platform; it does not substitute for a human decision where governance requires one.

Attribution Layers#

A single request can name several distinct parties. The platform stores them separately so audit, approvals, and incident review stay unambiguous:

• Authenticated principal — who presented credentials and passed authentication
• Subject — the primary subject of the access token
• Actor — the party acting on behalf of the subject when the request was delegated (typically the machine transport on a human-on-behalf-of call)
• Actor of record — who, in business terms, initiated the action
• Approver — who approved a sensitive action, when applicable

These layers do not have to coincide. They are recorded on operations and events so a later reader can answer not just what happened but who decided what, who carried it, and who approved it. Identity source (platform-managed vs federated) is kept explicit on human attribution.

Client-Scoped Identities#

In a B2B2X model, an enterprise often manages identities scoped to a specific Client rather than to the whole enterprise perimeter. Three composable patterns exist, and an enterprise can mix them — including for the same Client:

• Enterprise-driven client users — the enterprise creates and manages human users scoped to a Client. The end client does not log in directly; all human-governed actions on that client flow through enterprise-provisioned identities.
• Client-delegated client users — the enterprise delegates user management to the client. Client-scoped users authenticate to the platform directly and act within their own Client perimeter. The enterprise remains the relationship owner.
• Enterprise machine principals with cross-client scope — a service principal scoped across a subset or all of the enterprise's clients, for programmatic access without per-client human users.

A single Client can carry several patterns at once. Authorization resolves per principal × target perimeter, and audit always names the actor of record alongside the target client and account.

How This Appears In The API#

POST /service-accounts

{
  "parent": "enterprises/33333333-3333-4333-8333-333333333333",
  "display_name": "Treasury automation"
}

{
  "id": "77777777-7777-4777-8777-777777777777",
  "resource": "service-accounts/77777777-7777-4777-8777-777777777777",
  "parent": "enterprises/33333333-3333-4333-8333-333333333333",
  "display_name": "Treasury automation",
  "client_id": "sa_live_77777777777777777777",
  "client_secret": "<shown once at creation>"
}