> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module — identity (IDN)

> The organizational realm and the platform's access control plane. Schema identity. Established by ADR-022.

Depends on nothing. No other module reads its tables — they receive an already-resolved
authorization context from the API layer.

| Document                                                                                                          | Purpose                                                             |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`prd.md`](/modules/identity/prd)                                                                                 | What the module is, for whom, non-goals, success, phases            |
| [`spec.md`](/modules/identity/spec)                                                                               | The living technical shape: entities, invariants, events, endpoints |
| [`features/`](https://github.com/softcrumlabs/softcrum-suite/tree/master/docs/internal/modules/identity/features) | The feature specs — the units of delivery                           |

Spanish mirror: [`../../es/modules/identity/`](/es/modules/identity/overview). English is authoritative.

## Feature roadmap

Nine deliveries. Six make F1a, because nothing in the platform can be built without an
authenticated caller and a permission to check.

| FS                                                                             | Feature                                           | Phase | Depends on | Status  |
| ------------------------------------------------------------------------------ | ------------------------------------------------- | ----- | ---------- | ------- |
| [FS-IDN-0001](/modules/identity/features/fs-idn-0001-organizations-and-users)  | Organizations, users, memberships and invitations | F1a   | —          | `draft` |
| [FS-IDN-0002](/modules/identity/features/fs-idn-0002-permission-registry-rbac) | Permission registry and RBAC                      | F1a   | 0001       | `draft` |
| [FS-IDN-0003](/modules/identity/features/fs-idn-0003-authentication-methods)   | Authentication methods                            | F1a   | 0001       | `draft` |
| [FS-IDN-0004](/modules/identity/features/fs-idn-0004-sessions-and-devices)     | Sessions and device management                    | F1a   | 0003       | `draft` |
| [FS-IDN-0005](/modules/identity/features/fs-idn-0005-mfa)                      | Multi-factor authentication                       | F1a   | 0003       | `draft` |
| [FS-IDN-0006](/modules/identity/features/fs-idn-0006-api-keys)                 | Machine credentials — API keys                    | F1a   | 0002       | `draft` |
| [FS-IDN-0007](/modules/identity/features/fs-idn-0007-oauth-provider)           | OAuth2 provider                                   | F1b   | 0002, 0006 | `draft` |
| [FS-IDN-0008](/modules/identity/features/fs-idn-0008-social-sso)               | Social login and enterprise SSO                   | F1b   | 0003       | `draft` |
| [FS-IDN-0009](/modules/identity/features/fs-idn-0009-impersonation)            | Support impersonation                             | F1b   | 0002, 0004 | `draft` |

## The cut, explained

* **Permission registry before everything that uses it** (`0002`). It is a generated artifact: routes
  declare permissions, the registry is built from those declarations, and CI fails on drift. Every
  other module's endpoints depend on it existing.
* **Authentication and sessions are separate** (`0003`, `0004`). Proving who you are and keeping you
  proven are different problems: one is a credential exchange, the other is revocation, device
  inventory and expiry. They fail differently.
* **API keys are F1a, OAuth2 is F1b** (`0006`, `0007`). A server-to-server integration needs a key on
  day one. An OAuth2 provider with a consent screen is a product surface and can follow — but the
  scope model it renders is defined in `0002` from the start, so it is additive.
* **Impersonation last** (`0009`), because it is the most dangerous capability in the platform and
  should not exist before the audit trail that constrains it does.

## The two realms

|               | `identity` (organizational)             | `core` (member)                                                     |
| ------------- | --------------------------------------- | ------------------------------------------------------------------- |
| Who           | Tenant staff, Softcrum operators        | The tenant's end customers                                          |
| Our role      | **Controller**                          | **Processor**                                                       |
| Credentials   | password, magic link, passkey, SSO, MFA | OTP, magic link, token exchange                                     |
| Uniqueness    | per organization                        | per tenant                                                          |
| Token reaches | Console, Management API, Ops            | Runtime member endpoints only                                       |
| Spec          | this module                             | [FS-CORE-0009](/modules/core/features/fs-core-0009-member-identity) |

A token from one realm can **never** satisfy the other. That is structural, not a check.

## OAuth in both directions

| Direction | Softcrum is      | Spec                                                                 | What it enables                                                                                                |
| --------- | ---------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Outbound  | the **provider** | [FS-IDN-0007](/modules/identity/features/fs-idn-0007-oauth-provider) | A partner tool acts on a tenant's behalf · a tenant's site offers "Sign in with Softcrum" to its own customers |
| Inbound   | the **client**   | [FS-IDN-0008](/modules/identity/features/fs-idn-0008-social-sso)     | A tenant's staff sign in through their own IdP, or through Google, Microsoft or GitHub                         |

Neither is the default. A tenant may run both at once — staff inward through their corporate IdP,
customers outward through our provider.