> ## 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.

# Identity — APIs y liberación

> Todos los endpoints del realm organizacional: organizaciones, usuarios, roles, autenticación, MFA, credenciales de máquina y OAuth2.

Cada endpoint declara **exactamente un permiso** (R16) y pertenece a **una sola clase de SLO**
(DEC-D7). Hasta que su entrega esté lista el endpoint no existe, ni siquiera devolviendo 501.

## Cómo se lee la columna *Desde*

Todo lo de esta página pertenece a **[`R1 · Identity`](/releases/r1-identity)**, una de las cinco entregas de
[Release 1](/releases/overview) (`2026.11`). Las fases F1a/F1b/F2 son **orden de construcción**
dentro del release, no versiones ([ADR-025](/adr/adr-025-release-model)). La columna *Orden* dice
cuándo se construye: `1` lo que bloquea al resto, `2` lo que completa la propuesta.

## Management API — SLO p95 \<1 s

| Recurso         | Endpoints                                                                                                              | Permisos                                      | Desde           | Orden | Spec                                                                           |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------- | ----- | ------------------------------------------------------------------------------ |
| Organizaciones  | CRUD `/v1/identity/organizations`                                                                                      | `identity.organizations.{read,create,update}` | `R1 · Identity` | 1     | [FS-IDN-0001](/modules/identity/features/fs-idn-0001-organizations-and-users)  |
| Usuarios        | CRUD `/v1/identity/users`                                                                                              | `identity.users.{read,create,update}`         | `R1 · Identity` | 1     | [FS-IDN-0001](/modules/identity/features/fs-idn-0001-organizations-and-users)  |
| Membresías      | `GET·POST·DELETE /v1/identity/memberships`                                                                             | `identity.memberships.{read,create,delete}`   | `R1 · Identity` | 1     | [FS-IDN-0001](/modules/identity/features/fs-idn-0001-organizations-and-users)  |
| Invitaciones    | `POST /v1/identity/invitations` · `POST /v1/identity/invitations/{id}/resend` · `POST /v1/identity/invitations/accept` | `identity.invitations.{read,create}`          | `R1 · Identity` | 1     | [FS-IDN-0001](/modules/identity/features/fs-idn-0001-organizations-and-users)  |
| Permisos        | `GET /v1/identity/permissions`                                                                                         | `identity.permissions.read`                   | `R1 · Identity` | 1     | [FS-IDN-0002](/modules/identity/features/fs-idn-0002-permission-registry-rbac) |
| Roles           | CRUD `/v1/identity/roles` · `PUT /v1/identity/roles/{id}/permissions`                                                  | `identity.roles.{read,create,update}`         | `R1 · Identity` | 1     | [FS-IDN-0002](/modules/identity/features/fs-idn-0002-permission-registry-rbac) |
| Asignaciones    | `GET·POST·DELETE /v1/identity/role-assignments`                                                                        | `identity.roles.assign`                       | `R1 · Identity` | 1     | [FS-IDN-0002](/modules/identity/features/fs-idn-0002-permission-registry-rbac) |
| Sesiones        | `GET /v1/identity/sessions` · `DELETE /v1/identity/sessions/{id}`                                                      | `identity.sessions.{read,revoke}`             | `R1 · Identity` | 1     | [FS-IDN-0004](/modules/identity/features/fs-idn-0004-sessions-and-devices)     |
| MFA             | `POST /v1/identity/mfa/enroll` · `POST /v1/identity/mfa/verify` · `POST /v1/identity/mfa/recovery-codes`               | `identity.mfa.{read,manage}`                  | `R1 · Identity` | 1     | [FS-IDN-0005](/modules/identity/features/fs-idn-0005-mfa)                      |
| API keys        | `GET·POST /v1/identity/api-keys` · `POST /v1/identity/api-keys/{id}/rotate`                                            | `identity.api_keys.{read,create,rotate}`      | `R1 · Identity` | 1     | [FS-IDN-0006](/modules/identity/features/fs-idn-0006-api-keys)                 |
| Clientes OAuth2 | CRUD `/v1/identity/oauth-clients`                                                                                      | `identity.oauth_clients.{read,create,update}` | `R1 · Identity` | 2     | [FS-IDN-0007](/modules/identity/features/fs-idn-0007-oauth-provider)           |
| SSO             | CRUD `/v1/identity/sso-connections`                                                                                    | `identity.sso.{read,create,update}`           | `R1 · Identity` | 2     | [FS-IDN-0008](/modules/identity/features/fs-idn-0008-social-sso)               |
| Impersonación   | `POST /v1/identity/impersonations` · `DELETE /v1/identity/impersonations/{id}`                                         | `identity.impersonation.{start,stop}`         | `R1 · Identity` | 2     | [FS-IDN-0009](/modules/identity/features/fs-idn-0009-impersonation)            |

## Superficie OAuth2 y OIDC

No lleva permiso de los nuestros: la gobierna el protocolo. Es la superficie que consumen las
integraciones de nuestros tenants.

| Endpoint                                | Qué es                           | Desde           | Orden |
| --------------------------------------- | -------------------------------- | --------------- | ----- |
| `GET /oauth/authorize`                  | Inicio del flujo de autorización | `R1 · Identity` | 2     |
| `POST /oauth/token`                     | Emisión y refresco de tokens     | `R1 · Identity` | 2     |
| `GET /.well-known/openid-configuration` | Discovery OIDC                   | `R1 · Identity` | 2     |
| `GET /.well-known/jwks.json`            | Claves públicas de verificación  | `R1 · Identity` | 2     |

**El provider no inyecta permisos en el token.** Emite identidad; la autorización fina la resuelve
cada módulo contra el registro de permisos.

## Eliminar y purgar

Todo recurso de forma A expone las dos, con **permisos distintos**
([`standards/data.md`](/standards/data) §1b):

| Endpoint                                       | Qué hace                                                | Permiso                       | Reversible                     |
| ---------------------------------------------- | ------------------------------------------------------- | ----------------------------- | ------------------------------ |
| `DELETE /v1/identity/{{recurso}}/{{id}}`       | Soft delete: escribe `deleted_at`                       | `identity.{{recurso}}.delete` | Sí, con `POST /{{id}}/restore` |
| `DELETE /v1/identity/{{recurso}}/{{id}}/purge` | Hard delete: borra la fila, `409` si algo la referencia | `identity.{{recurso}}.purge`  | **No**                         |

Purgar exige haber eliminado antes. Las tablas append-only no exponen ninguna de las dos.

## Reglas que aplican a todos

* **Un permiso por endpoint** (R16), con la forma `identity.{{recurso}}.{{acción}}`.
* **Nuestras propias superficies consumen solo esta API** (R17).
* **Errores como RFC 9457** `problem+json` con un `code` estable, que es parte del contrato.
* **Los presupuestos de latencia son criterio de Definition of Done** (R18), verificados con prueba
  de carga en certificación.