Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

API de miembros

Lo que un programa puede hacer con los miembros de una organización: aprovisionarlos mediante SCIM 2.0 y seguir los cambios con webhooks. Las claves de API no pueden gestionar miembros ni invitaciones.

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:

TareaDónde hacerlo
Listar miembros, leer un miembro, ver su actividadPágina Miembros
Invitar personas, reenviar, recordar o revocar una invitaciónPágina Miembros (Invite Member)
Cambiar el rol o los grupos de un miembro, suspenderlo, eliminarloLa página del miembro
Editar roles, grupos y la matriz de permisosSettings > Access Control
Transferir la propiedadEn la aplicación (solo el propietario)
Crear, actualizar y desactivar miembros desde su proveedor de identidadSCIM 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étodoRutaÁmbitoFunción
GET/Usersscim:readListar miembros
POST/Usersscim:writeCrear un miembro; 201 con Location y ETag
GET/Users/{id}scim:readUn miembro, con su ETag
PUT/Users/{id}scim:writeReemplazar un miembro
PATCH/Users/{id}scim:writeCambiar algunos atributos
DELETE/Users/{id}scim:writeDesaprovisionar; 204
GET, POST/Groupslectura / escrituraListar o crear grupos
GET, PUT, PATCH, DELETE/Groups/{id}lectura / escrituraUn grupo
GET/ServiceProviderConfig, /ResourceTypes, /SchemasningunoDescubrimiento para proveedores de identidad

Las respuestas y los errores usan Content-Type: application/scim+json.

Cómo se asignan los atributos

Atributo SCIMEn Hermetry
idEl id del miembro en esta organización
userName, valor principal de emailsEl correo electrónico de la cuenta
externalIdEl ID externo de SCIM en la página del miembro (hasta 256 caracteres)
activeEstado del miembro: true Active, false Inactive
name, displayNameSe 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

EstadoscimTypeCuándo
400invalidFilterUn filtro distinto de userName eq o externalId eq
400invalidSyntax, invalidValueUn cuerpo que no es JSON o incumple el esquema
401ninguno«Invalid bearer token.»: el token es desconocido, ha caducado, es de otra organización o no tiene el ámbito
404ningunoNo hay ningún miembro con este id en su organización
409uniquenessEl correo ya está en uso, o la cuenta existe y no es miembro
412ningunoIf-Match no coincide con el ETag actual del miembro
429ninguno«Too many requests. Please slow down.»
501ningunoLos 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):

EventoSe envía cuando
member.created, member.updated, member.deletedUn miembro se añade, cambia o elimina
invitation.sent, invitation.accepted, invitation.declined, invitation.revokedUna invitación cambia de estado
scim.user.provisioned, scim.user.updated, scim.user.deprovisionedSu proveedor de identidad cambió un miembro mediante SCIM