People and groups
People are the users of your organization, and groups collect them so access can be granted once. Invite, enable, disable and remove users, and manage group membership.
List groups
Lists the organization's groups a page at a time, by name unless `sort` says otherwise, with each one's member count, live role binding count and whether it is the built-in Everyone group. `q` searches names and descriptions.
Create group
Creates a group with a name and optional description in the given organization. Requires the Org Owner or Org Admin role. Returns 201 with the group; a name already in use returns 409.
Delete group
Deletes a group together with its memberships and role bindings, revoking the access they gave. Requires the Org Owner or Org Admin role, and an Org Owner when the group holds Org Owner; the Everyone group cannot be deleted (409). Returns 204 with no body.
Get group
Returns one group with its description, member count and who created and last updated it. List its members with `GET /api/groups/{group_id}/members`.
Update group
Renames a group or changes its description; omitted fields stay unchanged. Requires the Org Owner or Org Admin role, and an Org Owner when the group holds Org Owner; renaming the Everyone group returns 409. Returns the group.
List group members
Lists a group's members a page at a time, by name unless `sort` says otherwise. `q` searches names and emails.
Remove group member
Removes one user from a group and revokes the access the group gave them. Requires the Org Owner or Org Admin role, and an Org Owner when the group holds Org Owner; the Everyone group returns 409. Returns 404 when the user is not a member, and 204 with no body otherwise.
Add group member
Adds one user of the group's organization to the group; an existing member is left as is. Requires the Org Owner or Org Admin role, and an Org Owner when the group holds Org Owner; the Everyone group returns 409. Returns 201 with the group.
List users
Lists the organization's users a page at a time, by email unless `sort` says otherwise, with profile, activation, last-seen and preference fields. `q` searches names and emails; `status` and, for the Jaah operator, `org` narrow the list. Requires permission to view users.
Create user
Creates a user in the given organization, adds them to the Everyone group and, unless `send_invitation` is false, emails an invitation whose outcome the `invitation` field reports without failing the create. Requires the Org Owner or Org Admin role. Returns 201 with the user, or 409 when the email is taken or the organization has reached its user limit.
Delete user
Permanently deletes a user and their group memberships. Requires the Org Owner or Org Admin role, and only an Org Owner may delete an Org Owner (403). Returns 409 for the caller, the organization's last Org Owner, or a user recorded as the author of other records; disable such a user instead.
Get user
Returns one user with their profile plus `effective_permission_keys`, the access picture the list omits. Requires permission to view users.
Update user
Updates a user's name, first and last name, email, description, password, preferences or selected git credential; only the fields sent change. Requires the Org Owner or Org Admin role, and only an Org Owner may edit an Org Owner; changing the caller's own email returns 403. A new password ends the user's open sessions; returns the user.
Disable user
Disables a user, idempotently: they can no longer use Jaah and their open sessions end, while their record and history stay. Requires the Org Owner or Org Admin role, and only an Org Owner may disable an Org Owner; the caller and the organization's last Org Owner return 409. Returns the user.
Enable user
Re-enables a disabled user, idempotently, so they can use Jaah again; sessions ended by the disable stay ended. Requires the Org Owner or Org Admin role, and only an Org Owner may enable an Org Owner; a user disabled by Jaah support returns 403. Returns the user.
Resend invitation
Emails the invitation again to a user who has not activated their account yet, and returns the recipient address. Requires the Org Owner or Org Admin role. Returns 409 once the user is active, while disabled or when email sending is not set up, 429 over the invitation rate limit, and 502 when the send fails.
Add membership
Adds a user to the group named by `group`. Requires the Org Owner or Org Admin role, and an Org Owner when the group holds Org Owner. Returns 201 with the membership, or 409 when it already exists or the group is Everyone.
Remove membership
Removes one group membership from a user and revokes the access it gave them. Requires the Org Owner or Org Admin role, and an Org Owner when the group holds Org Owner. The Everyone membership cannot be removed (409); returns 204 with no body.
List notification channels
Lists one user's notification channels (each with its own alert settings and their resolved levels), the alert groups that user sees, and which channel types may be added. Requires permission to view users.
Add user email
Adds an email address as one of a user's notification channels and mails it a confirmation link and a 6-digit code; it gets no alert until confirmed; an address the user has already confirmed is added confirmed, with no email. Requires the Org Owner or Org Admin role, and only for the caller's own account (the Jaah operator may act for anyone): adding an address for someone else returns 403. Returns 201 with the channel; 409 for an address already added, 429 over 10 addresses a day.
Delete user channel
Removes one of a user's notification channels, the account-email one included. Requires being an Owner or Admin of the user's organization.
Update notification channel
Changes one of a user's notification channels: send the whole `settings` document, or one `group` or `event` with its `level` (`off`, `brief` or `full`). Setting a group clears the alerts chosen inside it, and an Owner/Admin-only alert set for a member is refused. Requires being an Owner or Admin of the user's organization.
Resend user email
Mails an email channel's address a new confirmation link and code (for the account-email channel, a first one). Requires the Org Owner or Org Admin role, and only for the caller's own account (the Jaah operator may act for anyone); anyone else gets 403. Returns 202; 422 when already confirmed, 429 over 5 emails an hour to one address.
Verify user email
Confirms an email channel's address with the 6-digit code from its confirmation email, or the login email's for the account-email channel. Requires the Org Owner or Org Admin role, and only for the caller's own account (the Jaah operator may act for anyone); anyone else gets 403. A wrong, used or expired code returns 422 with a plain message; returns the channel.