# Organization API

Version 1.0 · OpenAPI 3.1.0

The Organization API: the people in your organization, its teams, custom
roles and who holds them, invitations, organization settings and its audit
log. Use it to keep EvoHub in step with your directory or HR system.

**Authentication.** Send an API key as `Authorization: Bearer evohub_…` or
`X-API-Key: evohub_…`. A key works in one organization. See *API keys and
scopes* and *Errors* in these docs.

**Permissions.** Each operation names the permission it needs
(`x-evohub-permission`); an API key needs it among its scopes. A key is always
held to its scopes, even one made by an administrator, and it never counts as
an organization owner or administrator: what only they may do (giving or
taking the Admin standing, editing an administrator, editing the default
roles) is refused with **403 `ADMIN_ONLY`**. A key can never grant more than it
holds: a role, invitation or team membership that would hand out a permission
the key does not hold is **403 `FORBIDDEN`**, naming the permission. A refusal
is never 401.

**What a key cannot do.** Signing in and everything a person does to their own
account (profile, password, two-factor authentication, sessions, connected
accounts, devices, switching or creating organizations, accepting
invitations), managing API keys and agents, the login policy, and deleting the
organization are for a person signed in to the console. Those routes are
listed in `x-route-check.not-public` with the reason; a key that calls one gets
**403**.

**Responses.** Success is `{"data": …, "success": true}`. Errors are
`{"error": {"code", "message", "request_id"}}`; `VALIDATION_FAILED` adds
`details`. `request_id` is the `X-Request-ID` of the response — quote it to
support. The codes are `VALIDATION_ERROR` (400, the message names the field),
`VALIDATION_FAILED`, `INVALID_BODY`, `UNKNOWN_PERMISSION`, `NOT_FOUND`,
`FORBIDDEN`, `ADMIN_ONLY`, `NOT_A_PERSON`, `SLUG_TAKEN` and `INTERNAL_ERROR`. Times are
RFC 3339 in UTC. Ids carry a type prefix (`usr_`, `team_`, `role_`, `inv_`,
`org_`).

**Chat apps** (Slack, Microsoft Teams) are connected in On-Call: see the
On-Call API reference.

## Servers

- `https://evohub.io`

## Authentication

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Members

The people in the organization.

- [GET /api/v1/users](https://docs-dev.evohub.io/organization/list-members.md): List members
- [GET /api/v1/users/{id}](https://docs-dev.evohub.io/organization/get-member.md): Get a member
- [DELETE /api/v1/users/{id}](https://docs-dev.evohub.io/organization/remove-member.md): Remove a member
- [PATCH /api/v1/users/{id}](https://docs-dev.evohub.io/organization/update-member.md): Update a member
- [GET /api/v1/users/{userId}/roles](https://docs-dev.evohub.io/organization/list-member-roles.md): List a member's roles

## Me

Who the key belongs to, and their own settings.

- [GET /api/v1/users/me](https://docs-dev.evohub.io/organization/get-me.md): Who the key belongs to
- [GET /api/v1/users/me/preferences](https://docs-dev.evohub.io/organization/get-my-preferences.md): Get email preferences
- [GET /api/v1/users/me/preferences/dashboard](https://docs-dev.evohub.io/organization/get-my-dashboard.md): Get the console home layout

## Teams

Teams and their members.

- [GET /api/v1/teams](https://docs-dev.evohub.io/organization/list-teams.md): List teams
- [POST /api/v1/teams](https://docs-dev.evohub.io/organization/create-team.md): Create a team
- [DELETE /api/v1/teams/{id}](https://docs-dev.evohub.io/organization/delete-team.md): Delete a team
- [PATCH /api/v1/teams/{id}](https://docs-dev.evohub.io/organization/update-team.md): Update a team
- [GET /api/v1/teams/{id}/members](https://docs-dev.evohub.io/organization/list-team-members.md): List a team's members
- [POST /api/v1/teams/{id}/members](https://docs-dev.evohub.io/organization/add-team-member.md): Add a member to a team
- [DELETE /api/v1/teams/{id}/members/{userId}](https://docs-dev.evohub.io/organization/remove-team-member.md): Remove a member from a team
- [GET /api/v1/teams/{id}/roles](https://docs-dev.evohub.io/organization/list-team-roles.md): List a team's roles

## Roles

Custom roles, the permission catalog, and who holds which role.

- [GET /api/v1/permissions](https://docs-dev.evohub.io/organization/list-permissions.md): List the permission catalog
- [GET /api/v1/roles](https://docs-dev.evohub.io/organization/list-roles.md): List roles
- [POST /api/v1/roles](https://docs-dev.evohub.io/organization/create-role.md): Create a role
- [DELETE /api/v1/roles/{id}](https://docs-dev.evohub.io/organization/delete-role.md): Delete a role
- [PATCH /api/v1/roles/{id}](https://docs-dev.evohub.io/organization/update-role.md): Update a role
- [GET /api/v1/roles/{id}/users](https://docs-dev.evohub.io/organization/list-role-users.md): List who holds a role directly
- [POST /api/v1/roles/{id}/users](https://docs-dev.evohub.io/organization/assign-role-to-user.md): Give a role to a member
- [DELETE /api/v1/roles/{id}/users/{userId}](https://docs-dev.evohub.io/organization/unassign-role-from-user.md): Take a role from a member
- [GET /api/v1/roles/{id}/teams](https://docs-dev.evohub.io/organization/list-role-teams.md): List the teams holding a role
- [POST /api/v1/roles/{id}/teams](https://docs-dev.evohub.io/organization/assign-role-to-team.md): Give a role to a team
- [DELETE /api/v1/roles/{id}/teams/{teamId}](https://docs-dev.evohub.io/organization/unassign-role-from-team.md): Take a role from a team

## Invitations

Invite people by email.

- [GET /api/v1/invitations](https://docs-dev.evohub.io/organization/list-invitations.md): List invitations
- [POST /api/v1/invitations](https://docs-dev.evohub.io/organization/create-invitation.md): Invite someone
- [POST /api/v1/invitations/{id}/resend](https://docs-dev.evohub.io/organization/resend-invitation.md): Resend an invitation
- [DELETE /api/v1/invitations/{id}](https://docs-dev.evohub.io/organization/delete-invitation.md): Cancel an invitation

## Organization

The organization's name and settings.

- [GET /api/v1/organizations](https://docs-dev.evohub.io/organization/get-organization.md): Get the organization
- [PATCH /api/v1/organizations/{id}](https://docs-dev.evohub.io/organization/update-organization.md): Rename the organization

## Audit log

Who changed what in the organization.

- [GET /api/v1/audit-logs](https://docs-dev.evohub.io/organization/list-audit-logs.md): List the audit log