Organization API

The Organization API lets a script keep EvoHub in step with your directory or HR system: list the people in your organization, create teams and fill them, define custom roles and give them to people or teams, invite new colleagues and read the organization's audit log. Every endpoint, with its parameters, schemas, errors and an example request, is in the Organization API reference. This page shows the common tasks and the rules that apply to all of them.

Paths below are relative to https://evohub.io. Requests need an API key, sent as described in API overview.

#Scopes

Each endpoint needs one scope. Give a key only the ones its job needs.

GET /api/v1/users/me, GET /api/v1/organizations and GET /api/v1/permissions need no scope. A key without the scope gets 403, never 401. See Errors.

#What a key cannot do

A key is held to its scopes, and it never counts as an owner or administrator, whoever created it. So:

• It cannot hand out more than it holds. A role, an invitation or a seat in a team that would give someone a permission the key does not hold is refused with 403 FORBIDDEN, and the message names the permission.
• It cannot do what only administrators do: give or take the Admin role or standing, edit an owner or administrator, edit the default roles. These return 403 ADMIN_ONLY.
• Some things are for a person in the console: signing in, everything about a person's own account (profile, password, two-factor authentication, sessions, devices, the list of their organizations, switching or creating organizations, seeing and accepting their invitations), creating and revoking API keys, enrolling agents, the login policy and deleting the organization. A key gets 403 there. See API keys and scopes.
• An organization key is not a person. It cannot send invitations (403 NOT_A_PERSON); use a personal key. GET /api/v1/users/me answers it with 403 NOT_A_PERSON too, which means the key works but has no profile.

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

#List members

curl https://evohub.io/api/v1/users \
  -H "Authorization: Bearer $EVOHUB_API_KEY"

Each member has a role, their standing in the organization: owner, admin, member or viewer. Add ?permission=oncall:alert:respond to get only the people who hold a permission, for example to know who can be put on a rota.

#Keep a team in step with your directory

# Create the team once.
curl -X POST https://evohub.io/api/v1/teams \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Platform", "slug": "platform"}'

# Then add and remove people as your directory changes.
curl -X POST https://evohub.io/api/v1/teams/$TEAM_ID/members \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "'"$USER_ID"'", "role": "member"}'

curl -X DELETE https://evohub.io/api/v1/teams/$TEAM_ID/members/$USER_ID \
  -H "Authorization: Bearer $EVOHUB_API_KEY"

Adding someone who is already in the team only changes their place in it (admin, member or viewer). The person must already be a member of the organization; invite them first if not.

#Give access through a role

curl -X POST https://evohub.io/api/v1/roles \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Incident responder",
        "permissions": ["oncall:alert:read", "oncall:alert:respond", "oncall:incident:write"]
      }'

Give the role to a team with POST /api/v1/roles/{id}/teams and {"team_id": "…"}: everyone in the team holds it for as long as they are in it, so access follows your directory. Give it to one person with POST /api/v1/roles/{id}/users and {"user_id": "…"}. GET /api/v1/permissions lists every permission name a role can carry. See Roles and permissions.

#Invite someone

curl -X POST https://evohub.io/api/v1/invitations \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "deniz@acme.example", "role": "member", "team_ids": ["'"$TEAM_ID"'"]}'

The invitation is emailed and lasts seven days. role_ids and team_ids are what the person gets when they accept. An address that already has a pending invitation gets 409 INVITATION_PENDING: resend it with POST /api/v1/invitations/{id}/resend instead.

#Read the audit log

GET /api/v1/audit-logs?limit=200 lists who changed what in the organization, newest first, including sign-ins. Page with offset, and leave out noisy actions with exclude=user.login,user.logout. To read every product's audit trail in one place, use the EvoTrail API.

#Rules that apply everywhere

• Updates. PATCH on a member, a team or the organization keeps a field you leave out; "" clears a title or description, and a name (or the organization's slug) cannot be sent empty. A slug another organization uses is 409 SLUG_TAKEN. PATCH on a role replaces its name and description, and its permissions when you send them.
• Personal keys and me. GET /api/v1/users/me returns the person a personal key belongs to. Its permissions are what the person holds, not the key's scopes.
• Errors. This service answers a bad field with VALIDATION_ERROR and the field in the message, and an unexpected failure with INTERNAL_ERROR. Its error bodies carry request_id.

#Related

• Organization API reference
• API keys and scopes
• Roles and permissions
• Organizations and teams
• Errors