API REST de Directorio de Identidades

Fuente de contrato OpenAPI (schema): https://auth-backend-eje.app.com.bo/api/schema/

Base URL de integración para este capítulo: BASE_URL_IDP (definida en la Introducción del módulo).

Documentación API: BASE_URL_IDP/api/docs/

Prerrequisitos

Antes de consumir estos endpoints, el cliente debe:

1. Autenticar usuario con OAuth2/OIDC.
2. Obtener access_token válido.
3. Enviar Authorization: Bearer <token> en cada request.
4. Solicitar scopes suficientes para cada operación.

Esquema de seguridad del API:

• BearerAuth (HTTP Bearer JWT).

Scopes oficiales para API de directorio:

• directory:all:users:read
• directory:external:users:read
• directory:internal:users:read
• directory:admin:users:read

Reglas de acceso por alcance:

• directory:all:users:read: permite leer usuarios internos y externos.
• directory:external:users:read: limita lectura a usuarios externos.
• directory:internal:users:read: limita lectura a usuarios internos.
• directory:admin:users:read: habilita visualizar datos de usuarios administradores de sistema.

Menú de rutas de Directorio

Tag	Método	Ruta	Summary
Directory	GET	/api/v1/directory/users/	Listar identidades
Directory	GET	/api/v1/directory/users/{public_id}/	Detalle de identidad

Endpoint de schema

El contrato OpenAPI se expone en:

• GET /api/schema/

Parámetros opcionales soportados por el endpoint de schema:

• format: json o yaml
• lang: localización de etiquetas/descripciones del schema

Rutas absolutas

• BASE_URL_IDP/api/v1/directory/users/
• BASE_URL_IDP/api/v1/directory/users/{public_id}/

GET /api/v1/directory/users/

Retorna el directorio de identidades registradas en el IdP. Cada item de resultado sigue un formato equivalente al payload de userinfo OIDC.

Query params

Parámetro	Tipo	Requerido	Descripción
is_active	boolean	No	Filtrar por estado activo.
is_eje_sysadmin	boolean	No	Filtrar por rol administrador. Requiere scope directory:admin:users:read.
page	integer	No	Número de página.
page_size	integer	No	Resultados por página (máximo 100).
termino	string	No	Búsqueda por término clave.
tipo_usuario	string	No	Tipo de usuario: USUARIO_EXTERNO o USUARIO_INTERNO.

Respuesta 200

application/json con estructura paginada:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "sub": "abc123",
      "name": "Juan Perez",
      "given_name": "Juan",
      "family_name": "Perez",
      "preferred_username": "juan.perez",
      "email": "juan@example.com",
      "email_verified": true,
      "is_active": true,
      "tipo_usuario": "USUARIO_INTERNO",
      "nro_documento_identidad": "12345678",
      "nro_documento_identidad_verified": true,
      "fecha_nacimiento": "01/01/1990",
      "celular": "70000000"
    }
  ]
}

Respuestas de error

• 400 Bad Request: parámetros inválidos.
• 401 Unauthorized: token ausente, expirado o inválido.
• 403 Forbidden: sin permisos/scopes suficientes.

Scopes requeridos

Se evalúan los scopes del token según el tipo de usuario consultado:

• Lectura general de internos y externos: directory:all:users:read.
• Lectura restringida a externos: directory:external:users:read.
• Lectura restringida a internos: directory:internal:users:read.
• Para ver datos de usuarios administradores de sistema: directory:admin:users:read.

GET /api/v1/directory/users/{public_id}/

Retorna el detalle de una identidad por su public_id. La respuesta también es equivalente al formato de claims de userinfo OIDC.

Path params

Parámetro	Tipo	Requerido	Descripción
public_id	string	Sí	Identificador público de la identidad.

Respuesta 200

application/json:

{
  "sub": "abc123",
  "name": "Juan Perez",
  "given_name": "Juan",
  "family_name": "Perez",
  "preferred_username": "juan.perez",
  "email": "juan@example.com",
  "email_verified": true,
  "is_active": true,
  "nro_documento_identidad": "12345678",
  "nro_documento_identidad_verified": true
}

Respuestas de error

• 401 Unauthorized: token ausente, expirado o inválido.
• 403 Forbidden: token válido sin scope/permisos suficientes.
• 404 Not Found: no existe identidad para ese public_id.

Scopes requeridos

Para consultar un public_id, el token debe contar con scope compatible con el tipo de usuario objetivo (all, internal o external).

Si la identidad objetivo corresponde a un usuario administrador de sistema, además se requiere directory:admin:users:read.

Esquemas de respuesta

DirectoryIdentity

Campos reportados por identidad (el backend puede incluir claims adicionales):

• sub: string
• name: string
• given_name: string
• family_name: string
• preferred_username: string
• email: string (email)
• email_verified: boolean
• is_active: boolean
• tipo_usuario: string
• nro_documento_identidad: string
• nro_documento_identidad_verified: boolean
• fecha_nacimiento: string
• celular: string

PaginatedDirectoryIdentity

• count: integer
• next: string | null
• previous: string | null
• results: DirectoryIdentity[]

ApiErrorResponse

Formato estándar de error del directorio:

{
  "error_code": "insufficient_scope",
  "error_message": "El token no tiene permisos para acceder a este recurso.",
  "detail": "El token no tiene permisos para acceder a este recurso."
}

Campos:

• error_code (requerido)
• error_message (requerido)
• detail (opcional)

Ejemplos de consumo

Listar identidades:

curl 'BASE_URL_IDP/api/v1/directory/users/' \
	-H 'Authorization: Bearer ACCESS_TOKEN'

Listar con filtros y paginación:

curl 'BASE_URL_IDP/api/v1/directory/users/?is_active=true&tipo_usuario=USUARIO_INTERNO&page=1&page_size=20&termino=juan' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Detalle de identidad:

curl 'BASE_URL_IDP/api/v1/directory/users/8f9f9d10-xxxx-xxxx-xxxx-xxxxxxxxxxxx/' \
	-H 'Authorization: Bearer ACCESS_TOKEN'

Manejo de errores recomendado

• 401 Unauthorized: token ausente, expirado o inválido.
• 403 Forbidden: token válido pero sin scope/permisos suficientes.
• 400 Bad Request: filtros o parámetros inválidos.
• 404 Not Found: public_id inexistente.

Recomendaciones de seguridad

• El token de acceso es de corta duración y debe obtenerse uno nuevo para cada petición
• En caso de tokens obtenidos por interacción de usuario, usar refresh_token para renovar el token de acceso.
• Separar clientes confidenciales (backend) de clientes públicos (frontend SPA o mobile) y usar flujos de autorización distintos para cada caso.

Consideraciones de integración

• Para obtener listados, usar filtros y paginación según parámetros que exponga la implementación.
• Para detalle, reemplazar {public_id} por el identificador público de la identidad.
• Gestionar autorización con token OAuth2 válido y scopes acordes al caso de uso: directory:all:users:read, directory:external:users:read, directory:internal:users:read y directory:admin:users:read.
• El filtro is_eje_sysadmin y el acceso a datos de administradores de sistema requieren directory:admin:users:read.
• El campo results puede incluir claims OIDC adicionales definidos por el IdP.

Relación con estándares

• Portador de token (Bearer) conforme a RFC 6750.
• Scopes y autorización conforme a RFC 6749.
• Claims de identidad alineados al modelo de userinfo de OpenID Connect.