T
testing
API Reference: Users & Organizations Managing User Invitations via API

Manage your organization's members programmatically. This guide covers how to invite new users, track pending invitations, allow users to accept invites, and manage roles using the API.

Authentication Required

All endpoints require a valid bearer token. Ensure you are authenticated and have the necessary organization permissions before making requests.

The Invitation Workflow

The process of adding a new user to an organization involves actions from both the organization administrator and the invited user.

sequenceDiagram
    participant Admin
    participant API
    participant User
    
    Admin->>API: POST /v1/organization/{id}/user/invite
    API-->>User: Sends Invitation Email
    User->>API: GET /v1/invitations
    API-->>User: Returns pending invites
    User->>API: POST /v1/invitations/{id}/accept
    API-->>Admin: User added to organization

End-to-End Process

  1. 1

    Send the invitation

    As an organization admin, send an invite to a new user by providing their email address and intended role.

  2. 2

    Track pending invites

    Admins can monitor who hasn't responded yet by fetching the list of pending invitations for the organization.

  3. 3

    User retrieves their invites

    The invited user authenticates and retrieves a list of all their personal pending invitations across all organizations.

  4. 4

    User accepts the invite

    The user accepts a specific invitation using its unique ID, officially joining the organization.

API Endpoints Overview

Depending on your role, you will interact with different sets of endpoints.


Admin Privileges Required
Endpoints nested under /v1/organization/{organization_id}/* generally require the authenticated user to have an active admin role within that specific organization.

Organization Management (Admin)

Use these endpoints to manage the users and invitations within a specific organization.

ActionMethodEndpointDescription
Invite UserPOST/v1/organization/{organization_id}/user/inviteSends an invitation to a user to join the organization.
List PendingGET/v1/organization/{organization_id}/user/pendingReturns all unanswered invitations for the organization.
List All UsersGET/v1/organization/{organization_id}/userReturns all users (both active and pending).
List Active UsersGET/v1/organization/{organization_id}/user/activeReturns only users who have accepted their invites.
Update RolePATCH/v1/organization/{organization_id}/user/{user_id}/roleChanges an existing user's role (e.g., member to admin).
Remove UserDELETE/v1/organization/{organization_id}/user/{user_id}Removes a user or revokes a pending invitation.

When building UI dashboards, use the /active endpoint to display current members, and the /pending endpoint to display a separate "Awaiting Response" list.

Personal Invitations (User)

Use these endpoints when acting on behalf of the invited user.

ActionMethodEndpointDescription
List My InvitesGET/v1/invitationsLists all pending invitations sent to the authenticated user.
Accept InvitePOST/v1/invitations/{invitation_id}/acceptAccepts a specific invitation.

Examples

Inviting a user

To invite a user, make a POST request to the organization invite endpoint. You will typically need to provide the user's email and their assigned role in the request body.

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": "jane.doe@example.com",
    "role": "member"
  }'

Accepting an invitation

Once a user retrieves their invitation_id from the GET /v1/invitations endpoint, they can accept it:

curl -X POST https://api.example.com/v1/invitations/inv_987xyz/accept 
  -H "Authorization: Bearer $USER_API_TOKEN" 
  -H "Content-Type: application/json"

Frequently Asked Questions

How do I cancel a pending invitation?

To revoke an invitation before the user accepts it, use the DELETE /v1/organization/{organization_id}/user/{user_id} endpoint. This will invalidate the invitation link.

Can a user belong to multiple organizations?

Yes. The GET /v1/invitations endpoint returns an array of invitations across all organizations that have invited the user's email address. They can accept multiple invitations and switch between organizations in your application.

What happens if I update a user's role while their invite is pending?

It is recommended to cancel the pending invitation and send a new one with the correct role. The PATCH role endpoint is designed for active users who have already joined the organization.