Members and roles API

14 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/members

List members

Access

Permission members:read

Parameters

Name	In	Type	Required
page	query	integer	no
pageSize	query	integer	no
sort	query	enum	no
q	query	string	no
status	query	string	no
role	query	string	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • userIdstring (uuid)required
  • emailstringrequired
  • displayNamestringrequired
  • preferredNamestring | nullrequired
  • statusenumrequired

    one of "invited", "active", "suspended", "former"

  • rolesarray of enumrequired
  • employeeIdstring (uuid) or nullrequired
  • mfaEnrolledbooleanrequired
  • lockedUntilstring (date-time) or nullrequired
  • lastActiveAtstring (date-time) or nullrequired
  • createdAtstring (date-time)required
  • invitationobject or nullrequired

    • idstring (uuid)required
    • expiresAtstring (date-time)required
    • expiredbooleanrequired
• pageintegerrequired

  min -9007199254740991

• pageSizeintegerrequired

  min -9007199254740991

• totalintegerrequired

  min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/members/{id}

Get a member

Access

Permission members:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• userIdstring (uuid)required
• emailstringrequired
• displayNamestringrequired
• preferredNamestring | nullrequired
• statusenumrequired

  one of "invited", "active", "suspended", "former"

• rolesarray of enumrequired
• employeeIdstring (uuid) or nullrequired
• mfaEnrolledbooleanrequired
• lockedUntilstring (date-time) or nullrequired
• lastActiveAtstring (date-time) or nullrequired
• createdAtstring (date-time)required
• invitationobject or nullrequired

  • idstring (uuid)required
  • expiresAtstring (date-time)required
  • expiredbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

DELETE/api/v1/members/{id}/invitation

Revoke an invitation

Access

Permission members:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

POST/api/v1/members/{id}/invitation/resend

Resend an invitation (replaces the link)

Access

Permission members:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• memberobjectrequired

  • idstring (uuid)required
  • userIdstring (uuid)required
  • emailstringrequired
  • displayNamestringrequired
  • preferredNamestring | nullrequired
  • statusenumrequired

    one of "invited", "active", "suspended", "former"

  • rolesarray of enumrequired
  • employeeIdstring (uuid) or nullrequired
  • mfaEnrolledbooleanrequired
  • lockedUntilstring (date-time) or nullrequired
  • lastActiveAtstring (date-time) or nullrequired
  • createdAtstring (date-time)required
  • invitationobject or nullrequired

    • idstring (uuid)required
    • expiresAtstring (date-time)required
    • expiredbooleanrequired
• inviteUrlstring | nullrequired
• expiresAtstring (date-time)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

POST/api/v1/members/{id}/mfa/reset

Reset a member's two-step verification

Owner only. The member enrols again at next sign-in (subject to the MFA policy).

Access

Permission security_settings:update

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required
• 404 not_found

POST/api/v1/members/{id}/password-reset-link

Reset a member's password (email, or a one-time link for the owner)

Owner only, after a recent sign-in. With email configured the reset link goes to the member (forced reset by email; `url` is null). Without email the owner gets a link to hand over, shown once and valid 60 minutes. Refused for members who hold a role or belong to another organisation (the password is shared across organisations).

Access

Permission members:update

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

201 Success. object

• urlstring | nullrequired
• deliveryenumrequired

  one of "email", "link"

• expiresAtstring (date-time)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required
• 404 not_found
• 409 conflict

POST/api/v1/members/{id}/reactivate

Reactivate a suspended member

Access

Permission members:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• userIdstring (uuid)required
• emailstringrequired
• displayNamestringrequired
• preferredNamestring | nullrequired
• statusenumrequired

  one of "invited", "active", "suspended", "former"

• rolesarray of enumrequired
• employeeIdstring (uuid) or nullrequired
• mfaEnrolledbooleanrequired
• lockedUntilstring (date-time) or nullrequired
• lastActiveAtstring (date-time) or nullrequired
• createdAtstring (date-time)required
• invitationobject or nullrequired

  • idstring (uuid)required
  • expiresAtstring (date-time)required
  • expiredbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

PUT/api/v1/members/{id}/roles

Set a member's assigned roles

Owner only. Takes effect on the member's next request. The last active owner cannot lose the owner role.

Access

Permission member_roles:grant

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• rolesarray of enumrequired

Responses

200 Success. object

• idstring (uuid)required
• userIdstring (uuid)required
• emailstringrequired
• displayNamestringrequired
• preferredNamestring | nullrequired
• statusenumrequired

  one of "invited", "active", "suspended", "former"

• rolesarray of enumrequired
• employeeIdstring (uuid) or nullrequired
• mfaEnrolledbooleanrequired
• lockedUntilstring (date-time) or nullrequired
• lastActiveAtstring (date-time) or nullrequired
• createdAtstring (date-time)required
• invitationobject or nullrequired

  • idstring (uuid)required
  • expiresAtstring (date-time)required
  • expiredbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required
• 404 not_found
• 409 last_owner

GET/api/v1/members/{id}/sessions

A member's browser and mobile sessions

Access

Permission security_settings:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • idstringrequired
  • kindenumrequired

    one of "browser", "mobile"

  • devicestringrequired
  • ipstring | nullrequired
  • createdAtstring (date-time)required
  • lastActiveAtstring (date-time)required
  • currentbooleanrequired
  • authMethodstringrequired
  • appVersionstring | null

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

DELETE/api/v1/members/{id}/sessions/{sessionId}

Revoke one of a member's sessions or devices

Access

Permission security_settings:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes
sessionId	path	string	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/members/{id}/sign-out-everywhere

Sign a member out of every browser and device

Also unlinks the member's SSO sign-in methods in this organisation (`unlinked` counts them).

Access

Permission security_settings:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• revokedintegerrequired

  min -9007199254740991

• unlinkedintegerrequired

  min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/members/{id}/suspend

Suspend a member

Revokes their sessions and devices and refuses sign-in.

Access

Permission members:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• userIdstring (uuid)required
• emailstringrequired
• displayNamestringrequired
• preferredNamestring | nullrequired
• statusenumrequired

  one of "invited", "active", "suspended", "former"

• rolesarray of enumrequired
• employeeIdstring (uuid) or nullrequired
• mfaEnrolledbooleanrequired
• lockedUntilstring (date-time) or nullrequired
• lastActiveAtstring (date-time) or nullrequired
• createdAtstring (date-time)required
• invitationobject or nullrequired

  • idstring (uuid)required
  • expiresAtstring (date-time)required
  • expiredbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict, last_owner

POST/api/v1/members/{id}/unlock

Clear a member's sign-in lockout

Access

Permission security_settings:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/members/invitations

Invite someone by email

hr_admins may only invite members with no assigned roles, and may not link the invitation to a manager's employee record. An employee record that already has a (non-former) sign-in is refused with 409. Without email configured, the response carries a link to copy.

Access

Permission members:create

Request body

application/json, object, required

• emailstringrequired

  max length 254

• displayNamestringrequired

  min length 1 · max length 120

• rolesarray of enum

  default []

• employeeIdstring (uuid)

Responses

201 Success. object

• memberobjectrequired

  • idstring (uuid)required
  • userIdstring (uuid)required
  • emailstringrequired
  • displayNamestringrequired
  • preferredNamestring | nullrequired
  • statusenumrequired

    one of "invited", "active", "suspended", "former"

  • rolesarray of enumrequired
  • employeeIdstring (uuid) or nullrequired
  • mfaEnrolledbooleanrequired
  • lockedUntilstring (date-time) or nullrequired
  • lastActiveAtstring (date-time) or nullrequired
  • createdAtstring (date-time)required
  • invitationobject or nullrequired

    • idstring (uuid)required
    • expiresAtstring (date-time)required
    • expiredbooleanrequired
• inviteUrlstring | nullrequired
• expiresAtstring (date-time)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict