New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Members API

What a program can do with the members of an organisation: provision them over SCIM 2.0 and follow changes with webhooks. API keys cannot manage members or invitations.

This page is for administrators who want to manage the people of an organisation from a program. It explains what an API key may not do with members, how an identity provider creates and removes members over SCIM 2.0, and which webhook events report member changes.

What an API key cannot do

Members, invitations, roles and groups are managed in the app only. No API key can call these routes, whatever permissions you try to give it:

TaskWhere to do it
List members, read a member, see their activityMembers page
Invite people, resend, remind or revoke an invitationMembers page (Invite Member)
Change a member’s role or groups, suspend, removeThe member’s page
Edit roles, groups and the permission matrixSettings > Access Control
Transfer ownershipIn the app (Owner only)
Create, update and deactivate members from your identity providerSCIM 2.0 (below)

This is deliberate. A key can never hold permissions of the identity and access parts of Hermetry: members, invitations, organisation settings, API keys, sessions and sign-in. A leaked key must not be able to add a person, raise a role or invite an outside address. A key that calls a member or invitation route gets:

{ "message": "API key does not have the required permission.", "code": "FORBIDDEN" }

with status 403. Accepting or declining an invitation is done by the invited person while signed in; keys never work on account routes. See Authentication for the full rule.

Provision members with SCIM 2.0

SCIM lets your identity provider create, update and deactivate members. The setup in the app (the endpoint and the SCIM token) is on Single sign-on (SAML) and provisioning. This section is the route reference for an integration that calls SCIM itself.

All SCIM paths are under https://<your host>/tenant/<tenantId>/api/scim/v2. Send the SCIM token in Authorization: Bearer <token>. Reads need the scim:read scope, writes the scim:write scope. The token must belong to the organisation in the path.

MethodPathScopeDoes
GET/Usersscim:readList members
POST/Usersscim:writeCreate a member; 201 with Location and ETag
GET/Users/{id}scim:readOne member, with its ETag
PUT/Users/{id}scim:writeReplace a member
PATCH/Users/{id}scim:writeChange some attributes
DELETE/Users/{id}scim:writeDeprovision; 204
GET, POST/Groupsread / writeList or create groups
GET, PUT, PATCH, DELETE/Groups/{id}read / writeOne group
GET/ServiceProviderConfig, /ResourceTypes, /SchemasnoneDiscovery for identity providers

Answers and errors use Content-Type: application/scim+json.

How attributes map

SCIM attributeIn Hermetry
idThe member id in this organisation
userName, primary emails valueThe account e-mail
externalIdThe SCIM external ID on the member page (up to 256 characters)
activeMember status: true Active, false Inactive
name, displayNameStored when Keep names in step is on (the default) and the account belongs to your organisation only

A new member gets the SCIM default role (User unless you change it in the SCIM settings). Roles from groups are set in Groups and roles.

Lists

GET /Users reads startIndex (from 1), count (default 100, at most 200), sortBy and sortOrder (ascending or descending). The only filters are equality on userName or externalId:

GET /Users?filter=userName eq "ana@example.com"
GET /Users?filter=externalId eq "00u1a2b3c4"

Any other filter answers 400 with scimType invalidFilter.

Create rules

  • A new e-mail address creates the account and the member.
  • An account that already exists but is not a member of your organisation is refused with 409 (uniqueness): “An account with that userName already exists and is not a member of this organization. It joins by invitation.” Invite the person in the app first; after that, SCIM manages the membership.

Changes made by someone else

GET /Users/{id} returns an ETag. Send it in If-Match on PUT, PATCH or DELETE; if the member changed meanwhile the answer is 412. If-None-Match on a GET answers 304 when nothing changed.

Groups

Group routes answer 501 (“SCIM Groups are not enabled for this tenant.”) until Groups are switched on in the SCIM settings. With Groups on, a member’s role follows the groups mapped to roles. The last active Owner is never demoted by a group change.

Example

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, "…": "…" } ]
}

SCIM errors

StatusscimTypeWhen
400invalidFilterA filter other than userName eq or externalId eq
400invalidSyntax, invalidValueA body that is not JSON or breaks the schema
401none“Invalid bearer token.”: the token is unknown, expired, of another organisation or lacks the scope
404noneNo member with this id in your organisation
409uniquenessThe e-mail is taken, or the account exists and is not a member
412noneIf-Match does not match the member’s current ETag
429none“Too many requests. Please slow down.”
501noneGroups are not switched on

Follow member changes with webhooks

To keep another system in step without polling, subscribe a webhook to these events (see Webhooks):

EventSent when
member.created, member.updated, member.deletedA member is added, changed or removed
invitation.sent, invitation.accepted, invitation.declined, invitation.revokedAn invitation changes state
scim.user.provisioned, scim.user.updated, scim.user.deprovisionedYour identity provider changed a member over SCIM