These code examples demonstrate how to use the Cribl API to create two new API Credentials: one with the Admin Role at all levels and one with the Editor Role at the product level on a single Workspace.

To use these examples, you must first create an API Credential manually in the Cribl UI. This is necessary because Cribl API requests require a Bearer token, which you must generate using an existing API Credential. After you create the first API Credential, you can use it to retrieve a Bearer token to authenticate subsequent API requests, including this request to create a new API Credential. Read Authenticate in Cribl.Cloud and Hybrid Deployments to create an API Credential in the Cribl UI and retrieve a Bearer token.

About the Code Examples

​

The code examples use Bearer token authentication. Read the authentication documentation for the API to learn how to configure authentication. The Bearer token must be granted Organization Owner or Admin Permissions.

Replace the variables in the examples with the corresponding information for your Cribl deployment.

The resource configurations in the examples do not include all available body parameters. For a complete list of body parameters for each resource, refer to the endpoint documentation in the API Reference.

Create an API Credential with Admin Role at All Levels

​

The following example creates an API Credential with Admin at all levels (Organization, all Workspaces, and all Cribl products in all Workspaces). For this request, you only need to specify admin as the Organization Role. The API Credential automatically inherits the Admin Role at lower levels from the Organization-level Role.

The example also includes the optional ipAllowlist body parameter to demonstrate how to restrict API access for the API Credential to a specific IPv4 CIDR range. Replace the placeholder value with your range. Omitting ipAllowlist allows access for all IPs.

curl --request POST \
--url "https://gateway.cribl.cloud/v1/organizations/${organizationId}/api-credentials" \
--header "Authorization: Bearer ${token}" \
--header "Content-Type: application/json" \
--data '{
  "name": "Auto-Manage-WorkspacesAuto-Manage-Workspaces",
  "description": "Used for automated Workspace management",
  "enabled": true,
  "roles": {
    "organizationRole": "admin"
  },
  "ipAllowlist": [
    "203.0.113.0/24"
  ]
}'

Create an API Credential with Product-Level Editor Role in One Workspace

​

The following example creates an API Credential with specific Roles at the Organization, Workspace, and product levels:

• User on the Organization.
• User on the main Workspace.
• Editor on all Cribl products in the main Workspace.

The example also includes the optional ipAllowlist body parameter to demonstrate how to restrict API access for the API Credential to a specific IPv4 CIDR range. Replace the placeholder value with your range. Omitting ipAllowlist allows access for all IPs.

The Cribl API does not support configuring Roles for API Credentials at the resource level. For API Credentials that do not inherit resource-level Roles from higher levels, use the Cribl UI to share Cribl Search resources as needed. See inheritance details for Dataset Providers and Datasets, Dashboards, and Notebooks.

curl --request POST \
--url "https://gateway.cribl.cloud/v1/organizations/${organizationId}/api-credentials" \
--header "Authorization: Bearer ${token}" \
--header "Content-Type: application/json" \
--data '{
  "name": "Product-Editor",
  "description": "Editor Role on all Cribl Products",
  "enabled": true,
  "roles": {
    "organizationRole": "user",
    "workspaces": [
      {
        "workspaceId": "main",
        "workspaceRole": "user",
        "products": [
          {
            "product": "stream",
            "role": "editor"
          },
          {
            "product": "edge",
            "role": "editor"
          },
          {
            "product": "search",
            "role": "editor"
          },
          {
            "product": "lake",
            "role": "editor"
          }
        ]
      }
    ]
  },
  "ipAllowlist": [
    "203.0.113.0/24"
  ]
}'

Store and Protect the Client Secret

​

The response includes the configuration details for the new API Credential, including the clientId and clientSecret. Use the clientId and clientSecret values in requests to https://login.cribl.cloud/oauth/token to retrieve a Bearer token for the new API Credential for use in subsequent API requests.

Responses for GET requests that retrieve API Credentials do not include clientSecret. Only responses for requests to POST /api-credentials include it. You must manually copy the clientSecret value into your secret storage or use automation to write it directly to a secrets manager. You cannot retrieve the clientSecret later.

The clientSecret is sensitive information and should be kept private.

Rotate API Credentials

​

The management plane API Reference documents endpoints to create, list, retrieve, update, and delete API Credentials. Any client that can call these endpoints can rotate credentials as needed.

To rotate with the API:

1. Send a request to POST /v1/organizations/{organizationId}/api-credentials to create a new API Credential. Get the new clientId and clientSecret from the response.

2. Replace the old clientId and clientSecret values with the new values wherever they are used.

3. Confirm that the old clientId and clientSecret values are replaced and validate the new values.

4. Send a request to DELETE /v1/organizations/{organizationId}/api-credentials/{id} to delete the old API Credential.

Rotate API Credentials on a schedule and when access requirements change to limit how long a credential is usable. Use one API Credential per integration with only the Roles that each integration requires. That way, rotating one credential does not affect other workloads or integrations that authenticate with other API Credentials.