Managing your organization's members programmatically allows you to automate onboarding, synchronize roles with your internal identity provider, and easily audit access. This guide covers the API endpoints available to invite, update, and remove members within your organization.

Member Lifecycle

Understanding the lifecycle of a user in your organization helps you know which endpoints to call and when.

stateDiagram-v2
    [*] --> Pending : Invite User
    Pending --> Active : User Accepts Invite
    Active --> Active : Update Role / Doc Grants
    Active --> [*] : Remove User
    Pending --> [*] : Revoke Invite

Common Workflows

Here is a typical sequence for onboarding a new team member via the API.

1. 1

   Check existing members

   Before inviting someone, you might want to check if they are already in the organization by retrieving the active users list using GET /v1/organization/{organization_id}/user/active.

2. 2

   Send an invitation

   Use the POST /v1/organization/{organization_id}/user/invite endpoint to send an email invitation to the new user. They will appear in the pending invites list until they accept.

3. 3

   Assign specific permissions

   Once the user accepts and becomes active, you can adjust their access. For example, use PATCH /v1/organization/{organization_id}/users/{user_id}/documentations to grant them access to specific documentation resources.

Organization User Endpoints

Use the following endpoints to manage the users in your organization. Replace {organization_id} and {user_id} with the respective UUIDs in your system.

Inviting and Viewing Users

Example: Inviting a user

curl -X POST "https://api.example.com/v1/organization/org_123abc/user/invite" 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"email": "new.hire@example.com", "role": "reader"}'

Managing Personal Invitations

While organization admins manage invites from the organization side, individual users can view and accept invitations sent to them using these endpoints.

Managing Roles and Access

As your team changes, you can programmatically elevate or restrict user privileges.

Removing a User

User Preferences Endpoints

In addition to organization-level management, the API provides endpoints for managing individual user preferences. These are typically accessed in the context of the currently authenticated user.