Esta página es para administradores que quieren gestionar las personas de una organización desde un programa. Explica qué no puede hacer una clave de API con los miembros, cómo un proveedor de identidad crea y elimina miembros mediante SCIM 2.0, y qué eventos de webhook informan de los cambios en los miembros.
Lo que no puede hacer una clave de API
Los miembros, las invitaciones, los roles y los grupos se gestionan solo en la aplicación. Ninguna clave de API puede llamar a estas rutas, sin importar los permisos que intente asignarle:
| Tarea | Dónde hacerlo |
|---|---|
| Listar miembros, leer un miembro, ver su actividad | Página Miembros |
| Invitar personas, reenviar, recordar o revocar una invitación | Página Miembros (Invite Member) |
| Cambiar el rol o los grupos de un miembro, suspenderlo, eliminarlo | La página del miembro |
| Editar roles, grupos y la matriz de permisos | Settings > Access Control |
| Transferir la propiedad | En la aplicación (solo el propietario) |
| Crear, actualizar y desactivar miembros desde su proveedor de identidad | SCIM 2.0 (más abajo) |
Es intencionado. Una clave nunca puede tener permisos de las partes de identidad y acceso de Hermetry: miembros, invitaciones, ajustes de la organización, claves de API, sesiones e inicio de sesión. Una clave filtrada no debe poder añadir a una persona, subir un rol ni invitar a una dirección externa. Una clave que llame a una ruta de miembros o invitaciones recibe:
{ "message": "API key does not have the required permission.", "code": "FORBIDDEN" }
con el estado 403. Aceptar o rechazar una invitación lo hace la persona invitada con la sesión iniciada; las claves nunca funcionan en rutas de cuenta. Consulte Authentication para ver la regla completa.
Aprovisionar miembros con SCIM 2.0
SCIM permite que su proveedor de identidad cree, actualice y desactive miembros. La configuración en la aplicación (el endpoint y el token SCIM) está en Single sign-on (SAML) and provisioning. Esta sección es la referencia de rutas para una integración que llama a SCIM directamente.
Todas las rutas SCIM están bajo https://<your host>/tenant/<tenantId>/api/scim/v2. Envíe el token SCIM en Authorization: Bearer <token>. Las lecturas necesitan el ámbito scim:read, las escrituras el ámbito scim:write. El token debe pertenecer a la organización de la ruta.
| Método | Ruta | Ámbito | Función |
|---|---|---|---|
| GET | /Users | scim:read | Listar miembros |
| POST | /Users | scim:write | Crear un miembro; 201 con Location y ETag |
| GET | /Users/{id} | scim:read | Un miembro, con su ETag |
| PUT | /Users/{id} | scim:write | Reemplazar un miembro |
| PATCH | /Users/{id} | scim:write | Cambiar algunos atributos |
| DELETE | /Users/{id} | scim:write | Desaprovisionar; 204 |
| GET, POST | /Groups | lectura / escritura | Listar o crear grupos |
| GET, PUT, PATCH, DELETE | /Groups/{id} | lectura / escritura | Un grupo |
| GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | ninguno | Descubrimiento para proveedores de identidad |
Las respuestas y los errores usan Content-Type: application/scim+json.
Cómo se asignan los atributos
| Atributo SCIM | En Hermetry |
|---|---|
id | El id del miembro en esta organización |
userName, valor principal de emails | El correo electrónico de la cuenta |
externalId | El ID externo de SCIM en la página del miembro (hasta 256 caracteres) |
active | Estado del miembro: true Active, false Inactive |
name, displayName | Se guardan cuando Keep names in step está activado (por defecto) y la cuenta pertenece solo a su organización |
Un miembro nuevo recibe el rol SCIM por defecto (User, salvo que lo cambie en los ajustes de SCIM). Los roles procedentes de grupos se definen en Groups and roles.
Listas
GET /Users lee startIndex (desde 1), count (por defecto 100, como máximo 200), sortBy y sortOrder (ascending o descending). Los únicos filtros son la igualdad en userName o externalId:
GET /Users?filter=userName eq "ana@example.com"
GET /Users?filter=externalId eq "00u1a2b3c4"
Cualquier otro filtro responde 400 con scimType invalidFilter.
Reglas de creación
- Una dirección de correo nueva crea la cuenta y el miembro.
- Una cuenta que ya existe pero que no es miembro de su organización se rechaza con
409(uniqueness): «Ya existe una cuenta con ese userName y no es miembro de esta organización. Se une por invitación.» Invite primero a la persona en la aplicación; después, SCIM gestiona la pertenencia.
Cambios hechos por otra persona
GET /Users/{id} devuelve un ETag. Envíelo en If-Match en PUT, PATCH o DELETE; si el miembro cambió entretanto, la respuesta es 412. If-None-Match en un GET responde 304 cuando no ha cambiado nada.
Grupos
Las rutas de grupos responden 501 («SCIM Groups are not enabled for this tenant.») hasta que los grupos se activen en los ajustes de SCIM. Con los grupos activados, el rol de un miembro sigue a los grupos asignados a roles. El último propietario activo nunca se degrada por un cambio de grupo.
Ejemplo
curl 'https://<your-host>/tenant/{tenantId}/api/scim/v2/Users?filter=userName%20eq%20%22ana@example.com%22' \
-H 'Authorization: Bearer sk_live_…'
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [ { "id": "4b2e…", "userName": "ana@example.com", "active": true, "…": "…" } ]
}
Errores de SCIM
| Estado | scimType | Cuándo |
|---|---|---|
| 400 | invalidFilter | Un filtro distinto de userName eq o externalId eq |
| 400 | invalidSyntax, invalidValue | Un cuerpo que no es JSON o incumple el esquema |
| 401 | ninguno | «Invalid bearer token.»: el token es desconocido, ha caducado, es de otra organización o no tiene el ámbito |
| 404 | ninguno | No hay ningún miembro con este id en su organización |
| 409 | uniqueness | El correo ya está en uso, o la cuenta existe y no es miembro |
| 412 | ninguno | If-Match no coincide con el ETag actual del miembro |
| 429 | ninguno | «Too many requests. Please slow down.» |
| 501 | ninguno | Los grupos no están activados |
Seguir los cambios de miembros con webhooks
Para mantener otro sistema sincronizado sin sondeo, suscriba un webhook a estos eventos (consulte Webhooks):
| Evento | Se envía cuando |
|---|---|
member.created, member.updated, member.deleted | Un miembro se añade, cambia o elimina |
invitation.sent, invitation.accepted, invitation.declined, invitation.revoked | Una invitación cambia de estado |
scim.user.provisioned, scim.user.updated, scim.user.deprovisioned | Su proveedor de identidad cambió un miembro mediante SCIM |

