# Identity

> Actor types, how human actors are sourced (platform-hosted vs federated), acting on behalf of a human via token exchange, and attribution layers.

Source: https://business-api-docs.youhodler.com/docs/concepts/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](/docs/concepts/access).

> **Practical rule:** Use service accounts for machine-to-machine traffic. Use human users for console operators and federated identities. Never share a credential between a human and an automation.

## 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](https://www.rfc-editor.org/rfc/rfc8693)): 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

**Request URL — POST**
```http
POST /service-accounts
```
**Request Body — application/json**
```json
{
  "parent": "enterprises/33333333-3333-4333-8333-333333333333",
  "display_name": "Treasury automation"
}
```
**Response — application/json**
```json
{
  "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>"
}
```