Identity APIs

Why This Exists

This document defines API responsibilities for the Identity Domain. It does not define final OpenAPI specifications.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Identity APIs provide controlled access to account, authentication, membership, authorization, session, API key, invitation, and MFA workflows.

API Groups

API group	Responsibilities	Example endpoints
User Account API	Create, retrieve, disable, and manage user accounts.	GET /identity/users/{userId}, POST /identity/users/{userId}/disable
Authentication API	Sign in, sign out, refresh, and handle identity provider callbacks.	POST /identity/auth/sign-in, POST /identity/auth/sign-out
Membership API	Manage organization membership access.	GET /identity/organizations/{organizationId}/members, POST /identity/memberships
Invitation API	Create, accept, revoke, and inspect invitations.	POST /identity/invitations, POST /identity/invitations/{invitationId}/accept
Role API	Manage roles and role assignments.	GET /identity/roles, POST /identity/role-assignments
Permission API	Manage permissions and permission assignments.	GET /identity/permissions, POST /identity/permission-assignments
Authorization API	Evaluate access decisions for protected actions.	POST /identity/authorize
Session API	Inspect and revoke sessions.	GET /identity/sessions, POST /identity/sessions/{sessionId}/revoke
API Key API	Create, rotate, revoke, and inspect API keys.	POST /identity/api-keys, POST /identity/api-keys/{apiKeyId}/revoke
MFA API	Register, verify, challenge, and disable MFA factors.	POST /identity/mfa/factors, POST /identity/mfa/challenges
Audit API	Retrieve identity audit events where authorized.	GET /identity/audit-events

API Design Rules

• Authentication endpoints must be rate limited.
• Authorization endpoints must require actor, tenant, action, resource, and context.
• API key creation must return plaintext key only once.
• Session revocation must take effect for future authorization checks.
• Keycloak-specific endpoints must remain behind integration boundaries if introduced.
• Final endpoint schemas will be defined in later OpenAPI work.

Example Authorization Flow

sequenceDiagram
    participant Client
    participant IdentityAPI as Identity API
    participant Billing
    participant Domain as Target Domain

    Client->>IdentityAPI: POST /identity/authorize
    IdentityAPI->>Billing: Check entitlement signal
    Billing-->>IdentityAPI: Entitlement result
    IdentityAPI->>IdentityAPI: Evaluate tenant, role, permission, policy
    IdentityAPI-->>Client: Allow or deny
    Client->>Domain: Execute only when allowed