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

Manage role-based access control (RBAC) for your organization directly through the API. This guide walks you through the complete lifecycle of managing users—from inviting them to your organization to updating their roles and specific documentation grants.

flowchart LR
    A["Invite User"] --> B["Pending Status"]
    B --> C["User Accepts"]
    C --> D["Active Member"]
    D --> E["Update Role"]
    D --> F["Manage Doc Grants"]

Prerequisites

Before you start managing user roles, ensure you have:

  • An active API key with Admin privileges.

  • Your organization_id. You can retrieve this by calling GET /v1/organization.


Only organization administrators can invite users, modify roles, or remove members. Ensure your API token has the necessary scopes before making these requests.

Managing User Roles

Updating a user's role requires you to know their specific user_id. Here is the standard workflow for locating a user and modifying their permissions.

  1. 1

    Find the User ID

    First, retrieve the list of users in your organization to find the user_id of the person you want to update. You can filter by active users or get the entire list.

    curl https://api.gitdocai.com/v1/organization/{organization_id}/user 
  -H "Authorization: Bearer YOUR_API_KEY"
  2. 2

    Update the user's role

    Once you have the user_id, send a PATCH request to update their role.

    curl -X PATCH https://api.gitdocai.com/v1/organization/{organization_id}/user/{user_id}/role 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"role": "admin"}'
  3. 3

    Verify the change

    You will receive a 200 OK response confirming the role update. The user's new permissions will take effect immediately.

Granular Documentation Grants

Sometimes you don't want to give a user full administrative access, but they need specific access to certain documentation projects. You can manage these specific grants using the documentations endpoint.

curl -X PATCH https://api.gitdocai.com/v1/organization/{organization_id}/users/{user_id}/documentations 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"documentation_ids": ["doc_123", "doc_456"]}'


Current Limitation: Adding or removing documentation grants on a specific member is currently restricted to Reader roles only. Write and Admin grants at the document level are planned for a future release.

User Preferences

In addition to role-based access, you can manage individual user preferences. Use these endpoints to get, set, or delete user-specific settings.

ActionMethodEndpoint
Get a PreferenceGET/preference
Set a PreferencePUT/preference
Delete a PreferenceDELETE/preference
List All PreferencesGET/preferences

Endpoint Reference

Use these endpoints to build your own user management dashboard or automate onboarding workflows.

ActionMethodEndpoint
Invite UserPOST/v1/organization/{org_id}/user/invite
List My Pending InvitationsGET/v1/invitations
Accept InvitationPOST/v1/invitations/{invitation_id}/accept
List All UsersGET/v1/organization/{org_id}/user
List Active UsersGET/v1/organization/{org_id}/user/active
List Pending InvitesGET/v1/organization/{org_id}/user/pending
Update RolePATCH/v1/organization/{org_id}/user/{user_id}/role
Manage Doc GrantsPATCH/v1/organization/{org_id}/users/{user_id}/documentations
Remove UserDELETE/v1/organization/{org_id}/user/{user_id}

Frequently Asked Questions

How do users accept an invitation?

When you invite a user via POST /v1/organization/{organization_id}/user/invite, they will appear in the pending invites list. The user must authenticate and call POST /v1/invitations/{invitation_id}/accept to join the organization.

Can I see invitations I've sent that haven't been accepted?

Yes. Use the GET /v1/organization/{organization_id}/user/pending endpoint to view all users who have been invited but have not yet accepted their invitations.

What happens when I remove a user?

Calling DELETE /v1/organization/{organization_id}/user/{user_id} immediately revokes the user's access to the organization and all associated documentation. Their account remains active, but they will no longer see your organization's resources.

Manage Organizations

Need to create or update the organization itself? Check out the Organization Management API reference.