API de Aplicaciones

Las aplicaciones en Auris representan apps cliente o servicios que se integran con la plataforma IAM — aplicaciones web, apps móviles, servidores de API, CLIs y servicios máquina a máquina. Cada aplicación tiene un Client ID (siempre visible) y opcionalmente un Client Secret (para clientes confidenciales). Auris soporta cuatro tipos de aplicaciones: WEB, MOBILE, API y M2M.

Todos los endpoints de esta sección requieren el permiso manage:applications y el encabezado x-tenant.

CRUD de Aplicaciones

GET/api/applicationsRequires: manage:applications

Lista todas las aplicaciones registradas en el tenant. Devuelve información resumida de cada aplicación incluyendo tipo, Client ID, URIs de redirección permitidas y fecha de creación.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20)
`type`	`WEB` \| `MOBILE` \| `API` \| `M2M`	Filtrar por tipo de aplicación
`search`	string	Buscar por nombre de aplicación

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "app_abc123",
        "name": "My Web App",
        "type": "WEB",
        "clientId": "cid_abc123",
        "redirectUris": ["https://app.yourdomain.com/callback"],
        "allowedOrigins": ["https://app.yourdomain.com"],
        "createdAt": "2025-01-10T08:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

POST/api/applicationsRequires: manage:applications

Crea una nueva aplicación. Para los tipos WEB y MOBILE, se deben proporcionar redirectUris. Para el tipo M2M, no se requieren redirectUris pero los scopes M2M deben configurarse por separado. Se genera automáticamente un clientSecret que se devuelve solo en la respuesta de creación — guárdalo de forma segura. No puede recuperarse de nuevo; usa la rotación de secretos para generar uno nuevo.

Cuerpo de la solicitud


{
  "name": "My Dashboard",
  "type": "WEB",
  "redirectUris": [
    "https://app.yourdomain.com/callback",
    "http://localhost:3000/callback"
  ],
  "allowedOrigins": [
    "https://app.yourdomain.com",
    "http://localhost:3000"
  ]
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "app_def456",
    "name": "My Dashboard",
    "type": "WEB",
    "clientId": "cid_def456",
    "clientSecret": "cs_sk_...",
    "redirectUris": ["https://app.yourdomain.com/callback", "http://localhost:3000/callback"],
    "allowedOrigins": ["https://app.yourdomain.com", "http://localhost:3000"],
    "createdAt": "2025-02-18T12:00:00Z"
  }
}

El clientSecret solo se devuelve una vez en el momento de la creación. Guárdalo inmediatamente. Para clientes públicos (SPAs en el navegador y apps móviles), no uses el clientSecret — usa PKCE en su lugar.

Códigos de error

Código	HTTP	Descripción
`NAME_TAKEN`	409	Ya existe una aplicación con este nombre
`VALIDATION_ERROR`	400	Formato de URI de redirección inválido o campo requerido faltante

GET/api/applications/[id]Requires: manage:applications

Obtiene los detalles completos de una sola aplicación, incluyendo todos los campos de configuración. El clientSecret nunca se devuelve después de la creación — usa la rotación para generar uno nuevo.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "My Web App",
    "type": "WEB",
    "clientId": "cid_abc123",
    "redirectUris": ["https://app.yourdomain.com/callback"],
    "allowedOrigins": ["https://app.yourdomain.com"],
    "enableDeviceFlow": false,
    "enableCiba": false,
    "enableDpop": false,
    "enableM2m": false,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-02-01T15:30:00Z"
  }
}

PUT/api/applications/[id]Requires: manage:applications

Actualiza la configuración de una aplicación. Todos los campos son opcionales — solo se actualizan los campos proporcionados.

Cuerpo de la solicitud


{
  "name": "My Web App v2",
  "redirectUris": [
    "https://app.yourdomain.com/callback",
    "https://staging.yourdomain.com/callback"
  ],
  "allowedOrigins": [
    "https://app.yourdomain.com",
    "https://staging.yourdomain.com"
  ],
  "enableDeviceFlow": false
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "My Web App v2",
    "redirectUris": [
      "https://app.yourdomain.com/callback",
      "https://staging.yourdomain.com/callback"
    ]
  }
}

DELETE/api/applications/[id]Requires: manage:applications

Elimina una aplicación. Esto revoca todos los tokens activos emitidos a la aplicación. Esta acción no puede deshacerse.

Respuesta exitosa


{
  "ok": true,
  "data": { "deleted": true }
}

Rotación de Secretos

PATCH/api/applications/[id]?action=rotate-secretRequires: manage:applications

Genera un nuevo client secret para la aplicación, invalidando inmediatamente el anterior. El nuevo secreto se devuelve una vez. Todas las integraciones que usen el secreto anterior deben actualizarse.

Rotar el secreto invalida inmediatamente el anterior. Los tokens M2M activos obtenidos con el secreto anterior continúan funcionando hasta que expiren, pero no se pueden obtener nuevos tokens.

Solicitud: No se requiere cuerpo.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "clientId": "cid_abc123",
    "clientSecret": "cs_sk_new...",
    "rotatedAt": "2025-02-18T14:00:00Z"
  }
}

Claims JWT Personalizados

Los claims personalizados permiten inyectar datos adicionales en los tokens de acceso emitidos por una aplicación específica. Los claims se resuelven en el momento de emisión del token y se incrustan en el payload del JWT.

Tipos de Valor

Tipo	Descripción	Ejemplo
`STATIC`	Valor de cadena fijo	`"plan": "enterprise"`
`USER_ATTRIBUTE`	Valor del atributo del perfil del usuario	`"email": user.email`
`ROLE_BASED`	Valor que cambia según los roles del usuario	`"tier": "admin"` si tiene el rol `admin`
`EXPRESSION`	Expresión personalizada evaluada en tiempo de ejecución	`user.roles.includes('admin') ? 'full' : 'read'`

Los claims JWT reservados (sub, iss, aud, exp, iat, jti, type, email, roles) no pueden ser sobrescritos por claims personalizados.

GET/api/applications/[id]/custom-claimsRequires: manage:applications

Lista todos los claims personalizados configurados para una aplicación.

Respuesta exitosa


{
  "ok": true,
  "data": [
    {
      "id": "claim_abc",
      "claimKey": "plan",
      "valueType": "STATIC",
      "staticValue": "enterprise",
      "isActive": true
    },
    {
      "id": "claim_def",
      "claimKey": "orgId",
      "valueType": "USER_ATTRIBUTE",
      "userAttribute": "organizationId",
      "isActive": true
    }
  ]
}

POST/api/applications/[id]/custom-claimsRequires: manage:applications

Crea un nuevo claim personalizado para una aplicación.

Cuerpo de la solicitud — Claim estático


{
  "claimKey": "plan",
  "valueType": "STATIC",
  "staticValue": "enterprise"
}

Cuerpo de la solicitud — Claim de atributo de usuario


{
  "claimKey": "department",
  "valueType": "USER_ATTRIBUTE",
  "userAttribute": "department"
}

Cuerpo de la solicitud — Claim basado en rol


{
  "claimKey": "accessLevel",
  "valueType": "ROLE_BASED",
  "roleMapping": {
    "admin": "full",
    "editor": "write",
    "viewer": "read"
  }
}

Cuerpo de la solicitud — Claim de expresión


{
  "claimKey": "isPremium",
  "valueType": "EXPRESSION",
  "expression": "user.roles.includes('premium') || user.roles.includes('admin')"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "claim_ghi",
    "claimKey": "plan",
    "valueType": "STATIC",
    "staticValue": "enterprise",
    "isActive": true
  }
}

Códigos de error

Código	HTTP	Descripción
`CLAIM_KEY_RESERVED`	400	La clave del claim es un campo JWT reservado
`CLAIM_KEY_TAKEN`	409	Ya existe un claim con esta clave para esta aplicación

PATCH/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Actualiza un claim personalizado. Soporta actualizaciones parciales — solo se cambian los campos proporcionados.

Cuerpo de la solicitud


{
  "staticValue": "professional",
  "isActive": false
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "claim_abc",
    "claimKey": "plan",
    "valueType": "STATIC",
    "staticValue": "professional",
    "isActive": false
  }
}

DELETE/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Elimina un claim personalizado. El claim dejará de aparecer en los tokens emitidos después de la eliminación.

Respuesta exitosa


{
  "ok": true,
  "data": { "deleted": true }
}

POST/api/applications/[id]/custom-claims/previewRequires: manage:applications

Previsualiza cómo se resolverían los claims personalizados para un usuario específico. Útil para probar la configuración de claims sin emitir un token real.

Cuerpo de la solicitud


{
  "userId": "usr_abc123"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "resolvedClaims": {
      "plan": "enterprise",
      "department": "Engineering",
      "accessLevel": "write",
      "isPremium": false
    }
  }
}

Scopes M2M

Los scopes M2M (Máquina a Máquina) definen qué puede hacer un token client_credentials. Los scopes son cadenas de texto libre que tu servidor de recursos valida.

GET/api/applications/[id]/m2m-scopesRequires: manage:applications

Lista los scopes M2M configurados para una aplicación.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "scopes": ["read:users", "manage:roles"],
    "allowedScopes": ["read:users", "manage:roles", "read:audit-logs"]
  }
}

scopes son los scopes predeterminados emitidos cuando no se especifica scope en la solicitud de token. allowedScopes son todos los scopes que la aplicación tiene permitido solicitar.

POST/api/applications/[id]/m2m-scopesRequires: manage:applications

Configura los scopes M2M para una aplicación. Reemplaza completamente la configuración de scopes existente.

Cuerpo de la solicitud


{
  "scopes": ["read:users"],
  "allowedScopes": ["read:users", "read:audit-logs"]
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "scopes": ["read:users"],
    "allowedScopes": ["read:users", "read:audit-logs"]
  }
}

Después de actualizar los scopes M2M, los tokens existentes siguen siendo válidos con sus scopes originales hasta que expiren. Las nuevas solicitudes de token usarán la configuración de scopes actualizada.

Relacionado

OAuth 2.0 y OIDC — Estándares de protocolo que implementan las aplicaciones
Claims JWT Personalizados — Configurar claims por aplicación en los tokens de acceso
Credenciales M2M Client Credentials — Autenticación servidor a servidor para apps M2M
Aplicaciones — Gestiona aplicaciones desde la Consola