Cribl User Management API Guide

Auth method: Bearer token (API token generated in Cribl UI; OAuth 2.0 / OIDC also supported for UI login but API calls use Bearer tokens)

Setup steps

1. Log in to the Cribl Stream UI as an admin.
2. Navigate to Settings > Access > API Tokens.
3. Create a new API token and assign appropriate roles/scopes.
4. Copy the generated token.
5. Include the token in API requests as: Authorization: Bearer

Required scopes

List all users

• Method: GET
• URL: /api/v1/users
• Watch out for: Returns all users in a single response; no pagination parameters documented.

Request example

GET /api/v1/users
Authorization: Bearer <token>

Response example

{
  "items": [
    {"id":"user1","username":"alice","roles":["admin"]}
  ],
  "count": 1
}

Get a specific user

• Method: GET
• URL: /api/v1/users/{id}
• Watch out for: Response is wrapped in an 'items' array even for single-user lookups.

Request example

GET /api/v1/users/user1
Authorization: Bearer <token>

Response example

{
  "items": [
    {"id":"user1","username":"alice","roles":["admin"],"email":"alice@example.com"}
  ]
}

Create a user

• Method: POST
• URL: /api/v1/users
• Watch out for: Password is required for local authentication users. Roles array must reference valid role IDs.

Request example

POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{"username":"bob","password":"s3cr3t","roles":["read"]}

Response example

{
  "items": [
    {"id":"user2","username":"bob","roles":["read"]}
  ]
}

Update a user

• Method: PATCH
• URL: /api/v1/users/{id}
• Watch out for: Only fields included in the request body are updated.

Request example

PATCH /api/v1/users/user2
Authorization: Bearer <token>
Content-Type: application/json

{"roles":["admin"]}

Response example

{
  "items": [
    {"id":"user2","username":"bob","roles":["admin"]}
  ]
}

Delete a user

• Method: DELETE
• URL: /api/v1/users/{id}
• Watch out for: Deleting the last admin user may lock out API access. No soft-delete; action is permanent.

Request example

DELETE /api/v1/users/user2
Authorization: Bearer <token>

Response example

{
  "items": [
    {"id":"user2"}
  ]
}

List roles

• Method: GET
• URL: /api/v1/roles
• Watch out for: Role IDs returned here are what must be passed in the 'roles' field when creating/updating users.

Request example

GET /api/v1/roles
Authorization: Bearer <token>

Response example

{
  "items": [
    {"id":"admin","title":"Admin"},
    {"id":"read","title":"Read Only"}
  ]
}

• Rate limits: Cribl's official documentation does not explicitly publish rate limit values or tiers for the REST API.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No rate limit specifications found in official docs. Contact Cribl support for enterprise rate limit details.

• Pagination method: none

• Default page size: 0

• Max page size: 0

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: Cribl Stream does not document native outbound webhooks for user-management events.

• Alternative event strategy: Use Cribl's notification system or poll the /api/v1/users endpoint for change detection.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• SCIM provisioning is not documented as a native feature of Cribl Stream.
• User provisioning must be done via the REST API or manually through the UI.

Three core automation scenarios are well-supported by the API.

First, provisioning a read-only user: call GET /api/v1/roles to retrieve valid role IDs, then POST /api/v1/users with username, password, and roles:["<read-role-id>"].

Password is required for local auth users;

SSO-provisioned users may not need it.

Second, elevating a user to Admin: GET /api/v1/users to find the target id, then PATCH /api/v1/users/{id} with {"roles":["admin"]}.

Critical caveat: the PATCH replaces the entire roles array - include all desired roles in the payload or existing roles will be dropped.

Third, deprovisioning a departed user: locate the user via GET /api/v1/users, optionally soft-disable with PATCH /api/v1/users/{id} using {"disabled": true}, then hard-delete with DELETE /api/v1/users/{id}.

Deletion is permanent and immediate with no soft-delete at the API level.

Avoid deleting the last Admin account - doing so may lock out all API access.

Provision a new read-only user

1. GET /api/v1/roles to retrieve valid role IDs and confirm the 'read' role ID.
2. POST /api/v1/users with username, password, and roles:["read"] in the request body.
3. Capture the returned user 'id' for future reference.
4. Optionally PATCH /api/v1/users/{id} to add email or name fields.

Watch out for: If using SSO/OIDC, password may not be required but local auth users must have a password set at creation.

Elevate a user to admin

1. GET /api/v1/users to find the target user's 'id'.
2. PATCH /api/v1/users/{id} with body {"roles":["admin"]}.
3. Verify the change with GET /api/v1/users/{id}.

Watch out for: Replacing the roles array overwrites existing roles; include all desired roles in the PATCH payload.

Deprovision a departed user

1. GET /api/v1/users to locate the user by username and retrieve their 'id'.
2. Optionally PATCH /api/v1/users/{id} with {"disabled": true} to disable without deleting.
3. DELETE /api/v1/users/{id} to permanently remove the user.

Watch out for: Deletion is permanent and immediate. Consider disabling first to allow audit review before hard deletion.

The most significant integration risk is the SSO re-provisioning loop: if an IdP is still active, a user deleted from Cribl's local store can be re-created automatically on next SSO login.

Any identity graph built on top of Cribl's /api/v1/users endpoint must account for this - a user's absence from the API response does not guarantee they cannot re-authenticate.

Rate limits are undocumented. Cribl's official API reference does not publish rate limit values, tiers, or rate-limit response headers. Automated pipelines polling /api/v1/users for change detection should implement conservative retry logic and back-off, and should contact Cribl support for enterprise-specific limits before building high-frequency integrations.

SCIM is not available. User provisioning must go through the REST API or the UI - there is no SCIM endpoint to target from an IdP or identity orchestration layer.

Teams building automated joiner-mover-leaver workflows against Cribl must own the full provisioning logic, including role resolution via GET /api/v1/roles and explicit disabled flag management for soft-offboarding.