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:
| Task | Where to do it |
|---|---|
| List members, read a member, see their activity | Members page |
| Invite people, resend, remind or revoke an invitation | Members page (Invite Member) |
| Change a member’s role or groups, suspend, remove | The member’s page |
| Edit roles, groups and the permission matrix | Settings > Access Control |
| Transfer ownership | In the app (Owner only) |
| Create, update and deactivate members from your identity provider | SCIM 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.
| Method | Path | Scope | Does |
|---|---|---|---|
| GET | /Users | scim:read | List members |
| POST | /Users | scim:write | Create a member; 201 with Location and ETag |
| GET | /Users/{id} | scim:read | One member, with its ETag |
| PUT | /Users/{id} | scim:write | Replace a member |
| PATCH | /Users/{id} | scim:write | Change some attributes |
| DELETE | /Users/{id} | scim:write | Deprovision; 204 |
| GET, POST | /Groups | read / write | List or create groups |
| GET, PUT, PATCH, DELETE | /Groups/{id} | read / write | One group |
| GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | none | Discovery for identity providers |
Answers and errors use Content-Type: application/scim+json.
How attributes map
| SCIM attribute | In Hermetry |
|---|---|
id | The member id in this organisation |
userName, primary emails value | The account e-mail |
externalId | The SCIM external ID on the member page (up to 256 characters) |
active | Member status: true Active, false Inactive |
name, displayName | Stored 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
| Status | scimType | When |
|---|---|---|
| 400 | invalidFilter | A filter other than userName eq or externalId eq |
| 400 | invalidSyntax, invalidValue | A body that is not JSON or breaks the schema |
| 401 | none | “Invalid bearer token.”: the token is unknown, expired, of another organisation or lacks the scope |
| 404 | none | No member with this id in your organisation |
| 409 | uniqueness | The e-mail is taken, or the account exists and is not a member |
| 412 | none | If-Match does not match the member’s current ETag |
| 429 | none | “Too many requests. Please slow down.” |
| 501 | none | Groups 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):
| Event | Sent when |
|---|---|
member.created, member.updated, member.deleted | A member is added, changed or removed |
invitation.sent, invitation.accepted, invitation.declined, invitation.revoked | An invitation changes state |
scim.user.provisioned, scim.user.updated, scim.user.deprovisioned | Your identity provider changed a member over SCIM |

