Suscripciones y funcionalidades

El endpoint de entitlements devuelve las suscripciones comerciales vigentes de un usuario junto con su producto, plan y funcionalidades. Incluye suscripciones personales y las heredadas mediante membresías activas en organizaciones.

Endpoint

POST /api/entitlements/lookup
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

La solicitud siempre requiere un access token válido. El cuerpo es opcional.

Consultar al usuario del token

Envía un cuerpo vacío o un objeto JSON vacío:

{}

Summit Auth obtiene el usuario desde el claim sub del access token. En este modo no se necesita un permiso adicional.

Consultar por correo

{
  "email": "member@example.com"
}

Consultar un usuario diferente al identificado por el token requiere el claim:

permission = api.productaccess.read

La API responde 403 Forbidden cuando el caller no tiene ese permiso. Esta misma respuesta se utiliza para un correo inexistente cuando el caller no está autorizado, evitando revelar qué direcciones están registradas.

Filtrar por organización

Agrega organizationId para incluir las suscripciones personales y solamente las suscripciones heredadas de esa organización:

{
  "email": "member@example.com",
  "organizationId": "11111111-2222-3333-4444-555555555555"
}

Si se omite organizationId, la respuesta incluye las suscripciones personales y las de todas las organizaciones donde el usuario tenga una membresía activa. Si el usuario no tiene una membresía activa en la organización indicada, la API responde 404 Not Found.

Respuesta

{
  "user": {
    "id": "USER_ID",
    "email": "member@example.com",
    "emailConfirmed": true
  },
  "subscriptions": [
    {
      "id": 25,
      "origin": "personal",
      "organization": null,
      "product": {
        "key": "summit_ai",
        "name": "Summit AI"
      },
      "plan": {
        "key": "pro",
        "name": "Pro"
      },
      "status": "active",
      "startsAt": "2026-08-01T00:00:00Z",
      "expiresAt": null,
      "features": [
        {
          "key": "storage",
          "name": "Almacenamiento",
          "value": 50,
          "unit": "GB"
        }
      ]
    },
    {
      "id": 31,
      "origin": "organization",
      "organization": {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Example Organization",
        "role": "Member"
      },
      "product": {
        "key": "mailu",
        "name": "Mailu"
      },
      "plan": {
        "key": "business",
        "name": "Business"
      },
      "status": "trialing",
      "startsAt": "2026-08-10T00:00:00Z",
      "expiresAt": "2026-08-24T00:00:00Z",
      "features": []
    }
  ]
}

subscriptions contiene únicamente suscripciones con estado active o trialing cuyo periodo se encuentre vigente. Los otorgamientos directos que no tienen una suscripción comercial asociada no aparecen en esta respuesta.

Campos de la suscripción

Campo	Descripción
`origin`	`personal` o `organization`.
`organization`	Organización y rol que originan el acceso; `null` para una suscripción personal.
`product`	Clave estable y nombre visible del producto.
`plan`	Clave estable y nombre visible del plan.
`status`	`active` o `trialing`.
`startsAt`	Inicio del periodo; puede ser `null`.
`expiresAt`	Fin del periodo; `null` significa que no expira.
`features`	Funcionalidades del plan, incluidos su valor y unidad opcionales.

Códigos de respuesta

Código	Motivo
`200`	Consulta completada. `subscriptions` puede estar vacío.
`401`	Token ausente o inválido, o token sin un usuario cuando no se envió `email`.
`403`	Consulta por correo sin `api.productaccess.read`.
`404`	Usuario no encontrado para un caller autorizado, o membresía organizacional inexistente/inactiva.