Authentication and organization scope

Protected endpoints accept a short-lived Privy access token in the HTTP Authorization header:

Authorization: Bearer <privy-access-token>

Do not send an identity token in this header. The consumer session bootstrap may accept an identity token in its validated request body so the API can synchronize linked identities; the bearer credential still authenticates the request.

Separate realms

Consumer and administrator identities are verified against separate Privy applications and verification keys.

• /v1/consumer/* requires a consumer-realm access token.
• /v1/admin/* requires an administrator-realm access token and an active platform-operator record.
• A valid consumer token does not grant administrator access.

Organization authorization

Authentication establishes the caller. It does not establish authority over an organization or its funds. For organization-scoped routes, the API loads the caller's active membership and checks the required role server-side.

Expect these outcomes:

• 401 when a token is absent, invalid, expired, or the application session has not been bootstrapped.
• 403 when the caller is authenticated but lacks the required realm, membership, role, or active status.
• 404 when a resource is unavailable within the caller's authorized organization scope.