BigID User Management API Guide

Auth method: Session token (Bearer token obtained via login endpoint)

Setup steps

1. POST credentials (username + password) to /api/v1/sessions to obtain a session token.
2. Include the token in subsequent requests as the Authorization header: 'Authorization: '.
3. Tokens expire after a configured session timeout; re-authenticate to obtain a new token.
4. For service accounts, create a dedicated user with appropriate roles and use its credentials programmatically.

Authenticate / create session

• Method: POST
• URL: /api/v1/sessions
• Watch out for: Token is returned as auth_token; use it directly as the Authorization header value (no 'Bearer' prefix in some versions).

Request example

POST /api/v1/sessions
Content-Type: application/json
{
  "username": "admin",
  "password": "secret"
}

Response example

{
  "auth_token": "eyJhbGci...",
  "systemUser": "admin"
}

List users

• Method: GET
• URL: /api/v1/users
• Watch out for: Pagination uses skip/limit query params. Total count may be in a separate field.

Request example

GET /api/v1/users?skip=0&limit=50
Authorization: <auth_token>

Response example

{
  "users": [
    {"id": "abc123", "name": "jdoe", "email": "jdoe@example.com", "role": "Admin"}
  ],
  "totalCount": 1
}

Get user by ID

• Method: GET
• URL: /api/v1/users/{userId}
• Watch out for: userId is the internal MongoDB ObjectId, not the username.

Request example

GET /api/v1/users/abc123
Authorization: <auth_token>

Response example

{
  "id": "abc123",
  "name": "jdoe",
  "email": "jdoe@example.com",
  "role": "Admin",
  "isEnabled": true
}

Create user

• Method: POST
• URL: /api/v1/users
• Watch out for: Local user creation only; SAML users are provisioned via IdP and cannot be created via this endpoint.

Request example

POST /api/v1/users
Authorization: <auth_token>
Content-Type: application/json
{
  "name": "jdoe",
  "email": "jdoe@example.com",
  "password": "P@ssw0rd",
  "role": "Viewer"
}

Response example

{
  "id": "def456",
  "name": "jdoe",
  "email": "jdoe@example.com",
  "role": "Viewer"
}

Update user

• Method: PUT
• URL: /api/v1/users/{userId}
• Watch out for: Full PUT semantics may require sending all fields; partial updates behavior is not clearly documented.

Request example

PUT /api/v1/users/def456
Authorization: <auth_token>
Content-Type: application/json
{
  "role": "Admin",
  "isEnabled": true
}

Response example

{
  "id": "def456",
  "name": "jdoe",
  "role": "Admin",
  "isEnabled": true
}

Delete user

• Method: DELETE
• URL: /api/v1/users/{userId}
• Watch out for: Deletion is permanent. Disabling (isEnabled: false) is preferred for audit trail retention.

Request example

DELETE /api/v1/users/def456
Authorization: <auth_token>

Response example

{
  "message": "User deleted successfully"
}

List roles

• Method: GET
• URL: /api/v1/roles
• Watch out for: Role names used in user create/update must exactly match names returned here.

Request example

GET /api/v1/roles
Authorization: <auth_token>

Response example

{
  "roles": [
    {"id": "r1", "name": "Admin"},
    {"id": "r2", "name": "Viewer"}
  ]
}

• Rate limits: No publicly documented rate limits found in official BigID documentation.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: Rate limit details are not publicly disclosed. Contact BigID support for enterprise-specific limits.

• Pagination method: offset

• Default page size: 50

• Max page size: Not documented

• Pagination pointer: skip / limit

• Webhooks available: No

• Webhook notes: No publicly documented webhook or event-subscription system for user management events was found in BigID's official documentation.

• Alternative event strategy: Poll the /api/v1/users endpoint periodically to detect changes, or use BigID's audit log API if available in your deployment.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• SCIM is not publicly documented by BigID.
• SAML SSO is supported (Okta, Entra ID) but automated SCIM provisioning is not confirmed.
• Contact BigID enterprise support to inquire about SCIM availability for your deployment.

Three scenarios cover the majority of programmatic user management needs:

• Provision a local user: POST /api/v1/sessions → GET /api/v1/roles (role name must exactly match) → POST /api/v1/users with name, email, password, and role → confirm via GET /api/v1/users/{newUserId}. SAML-origin users cannot be created through this endpoint.

• Disable a departed employee: Authenticate → paginate /api/v1/users to locate userId by email → PUT /api/v1/users/{userId} with isEnabled: false → confirm. Prefer disable over DELETE to preserve audit history. For SAML users, also disable in the IdP to prevent re-provisioning on next login.

• Bulk access review: Authenticate → GET /api/v1/users?skip=0&limit=50, record totalCount, iterate with increasing skip values → export id, name, email, role, isEnabled, and origin. No bulk export endpoint exists; pagination must be implemented manually.

Provision a new local user with a specific role

1. POST /api/v1/sessions with admin credentials to obtain auth_token.
2. GET /api/v1/roles to retrieve the exact role name/id needed.
3. POST /api/v1/users with name, email, password, and role fields.
4. Verify creation by GET /api/v1/users/{newUserId}.

Watch out for: Role name must exactly match the value returned by /api/v1/roles. SAML users cannot be created this way.

Disable a departed employee's account

1. POST /api/v1/sessions to authenticate.
2. GET /api/v1/users?skip=0&limit=100 and filter by email or name to find the userId.
3. PUT /api/v1/users/{userId} with isEnabled: false to deactivate without deleting.
4. Confirm with GET /api/v1/users/{userId} that isEnabled is false.

Watch out for: Prefer disabling over deleting to preserve audit history. For SAML users, also disable in the IdP to prevent re-provisioning on next login.

Bulk-list all users for an access review

1. POST /api/v1/sessions to authenticate.
2. GET /api/v1/users?skip=0&limit=50 and record totalCount.
3. Iterate with increasing skip values (50, 100, 150...) until all users are retrieved.
4. Export id, name, email, role, isEnabled, and origin fields for review.

Watch out for: There is no documented bulk export endpoint; pagination must be implemented manually. Large deployments may require many requests.

The session token model has no documented refresh mechanism - when a token expires, the service account must re-authenticate from scratch. This makes long-running automation jobs fragile without explicit retry and re-auth logic built in.

PUT /api/v1/users may require sending all fields (full replacement semantics); partial update behavior is not clearly documented, creating risk of accidentally overwriting role assignments or other fields. Always GET the current user object before issuing a PUT.

Base URL, available fields, and endpoint paths vary between BigID versions and between cloud and on-premises deployments. There is no fixed SaaS hostname. Any integration must be parameterized per deployment and validated against that instance's API documentation before running in production.