All Cribl API requests require you to authenticate with a Bearer token, except GET /health in the global context and POST /auth/login. In Cribl, Bearer tokens are JSON Web Tokens (JWTs).

You must include a valid Bearer token in the Authorization header of your API requests. The Bearer token verifies your identity and ensures secure access to the requested resources. The process for retrieving the Bearer token depends on whether you authenticate in commercial Cribl.Cloud and hybrid deployments, Cribl.Cloud Government and hybrid deployments, or on-prem deployments.

• In Cribl.Cloud and hybrid deployments, Bearer tokens are valid for 24 hours.

• In on-prem deployments, Bearer tokens expire according to the value you provide for the Auth token TTL setting at Settings > Global > General Settings > API Server Settings > Advanced. The default setting is 3600 seconds (1 hour).

You are responsible for ensuring that your applications obtain a new Bearer token within the expiration window for each token.

For on-prem deployments, if you’re using SSO/OpenID Connect Authentication, you must toggle on Allow login as Local User in Cribl (see Set Up Fallback Access). You’ll need to be a Local user when you authenticate.

To use https for on-prem requests, you must Configure TLS. If you do not configure TLS, use http instead. Use http only for testing in development environments. In production, configure TLS and use https to secure your communications.

Authenticate in Cribl.Cloud and Hybrid Deployments ​

To authenticate for API requests to control plane (Cribl.Cloud or hybrid) or management plane (Cribl.Cloud) endpoints, first create an API Credential. The API Credential provides a Client ID and Client Secret. Provide these in a request to https://login.cribl.cloud/oauth/token to obtain a 24-hour Bearer token to authenticate subsequent API requests.

The authentication process is the same for control plane and management plane access. The difference is the base URL and endpoints used for subsequent API requests.

For Cribl.Cloud Government, follow the separate authentication instructions instead.

You can create API Credentials with the POST /api-credentials endpoint in the Cribl management plane API. However, you must first create the initial API Credential manually in the Cribl UI. This is necessary because Cribl API requests require a Bearer token, which in turn requires an API Credential. After you create the first API Credential, you can retrieve a Bearer token to use in API requests to create new API Credentials.

To create an API Credential in the Cribl UI:

1. Log in to Cribl.Cloud as an Owner or an Admin.

2. On the top bar, select Products, and then select Cribl.

3. In the sidebar, select Organization, and then select API Credentials.

4. Select Add Credential.

5. Enter a Name and an optional Description.

6. In the Organization Permissions drop-down menu, select a Permission to apply for the API Credential. Organization Permissions are available on certain plan/license tiers. Without a proper license, all API Credentials are granted the Admin Permission.

   • Choosing the Admin or Owner Permission automatically grants admin access to all Workspaces.

   • If you choose the User Permission, under Workspace Access, define the desired Permissions for specific Workspaces and Cribl products.

   • To use the API Credential to grant read-only access on individual Cribl Search resources (for example, for a service account that connects to Cribl Search via API), select either the User or Editor Permission on Cribl Search. The Admin Permission automatically grants full access to all Cribl Search resources.

7. (Optional) Under IP Allowlist, you can restrict API access for the Credential to specific IPv4 Classless Inter-Domain Routing (CIDR) ranges. Select Add CIDR and enter the desired range. You can add a maximum of 10 CIDR ranges.

8. Select Save.

The API Credentials page displays the new API Credential within a few seconds.

The API Credential includes a Client ID and a Client Secret that Organization Owners and Admins can use to generate Bearer tokens. Organization Owners and Admins can view, edit, and disable existing API Credentials. Only Owners can delete API Credentials.

The Client ID and Client Secret are sensitive information and should be kept private.

Once you have the Client ID and Client Secret, send them in a request to https://login.cribl.cloud/oauth/token to retrieve the 24-hour Bearer token to use to authenticate subsequent API requests. The request body includes these fields:

• grant_type: The OAuth grant type. For API Credentials, the value is always client_credentials.
• client_id and client_secret: The Client ID and Client Secret from the API Credential. The Client ID and Client Secret are sensitive information and should be kept private, so the example request shows how to provide them as variables.
• audience: The API identifier for Cribl.Cloud in Auth0. The value is always https://api.cribl.cloud. This is not the URL to use for subsequent API requests, which require the appropriate base URL as shown in the API request example.

curl --request POST \
--url "https://login.cribl.cloud/oauth/token" \
--header "Content-Type: application/json" \
--data "{
  \"grant_type\": \"client_credentials\",
  \"client_id\": \"${clientId}\",
  \"client_secret\": \"${clientSecret}\",
  \"audience\": \"https://api.cribl.cloud\"
}"

As shown in the following example response, the JSON object in the response includes several attributes:

• access_token: The Bearer token to use in the Authorization header for authentication in subsequent API requests.
• scope: The Permissions that the Bearer token grants.
• expires_in: The number of seconds until the Bearer token expires. In Cribl.Cloud/hybrid, Bearer tokens expire 24 hours (86400 seconds) after they are created. You are responsible for ensuring that your applications obtain a new Bearer token within the expiration window for each token.
• token_type: The type of the token. in Cribl.Cloud/hybrid, the value is always Bearer.

{
  "access_token": "abcdefg1234567890...exampleBearerToken",
  "scope": "user:read:workergroups user:update:workergroups user:read:connections user:update:connections user:update:workspaces user:read:workspaces",
  "expires_in": 86400,
  "token_type": "Bearer"
}

To use the Bearer token in subsequent API requests, include it in the Authorization header as shown in this control plane example:

curl --request GET \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/${groupName}/system/inputs" \
--header "Authorization: Bearer abcdefg1234567890...exampleBearerToken" \
--header "Content-Type: application/json"

Authenticate in Cribl.Cloud Government and Hybrid Deployments ​

To authenticate for API requests to control plane endpoints in Cribl.Cloud Government and hybrid deployments, first create an API Credential. The API Credential provides a Client ID and Client Secret. Provide these in a request to https://criblgov-prod.okta.com/oauth2/ausfuanngyqh8CJ6c4h7/v1/token to obtain a 24-hour Bearer token to authenticate subsequent API requests.

Cribl.Cloud Government does not support management plane API endpoints or the IP Allowlist option for API Credentials.

API authentication request details differ between Cribl.Cloud Government and commercial Cribl.Cloud, such as the request URL, request header, and audience value. Follow the instructions and examples in this section.

To create an API Credential in the Cribl.Cloud Government UI:

1. Log in to Cribl.Cloud Government as an Owner or an Admin.

2. On the top bar, select Products, and then select Cribl.

3. In the sidebar, select Organization, and then select API Credentials.

4. Select Add Credential.

5. Enter a Name and an optional Description.

6. In the Organization Permissions drop-down menu, select a Permission to apply for the API Credential. Organization Permissions are available on certain plan/license tiers. Without a proper license, all API Credentials are granted the Admin Permission.

   • Choosing the Admin or Owner Permission automatically grants admin access to all Workspaces.

   • If you choose the User Permission, under Workspace Access, define the desired Permissions for specific Workspaces and Cribl products.

   • To use the API Credential to grant read-only access on individual Cribl Search resources (for example, for a service account that connects to Cribl Search via API), select either the User or Editor Permission on Cribl Search. The Admin Permission automatically grants full access to all Cribl Search resources.

7. Select Save.

The API Credentials page displays the new API Credential within a few seconds.

The API Credential includes a Client ID and a Client Secret that Organization Owners and Admins can use to generate Bearer tokens. Organization Owners and Admins can view, edit, and disable existing API Credentials. Only Owners can delete API Credentials.

The Client ID and Client Secret are sensitive information and should be kept private. Client IDs and Client Secrets are not interchangeable between commercial Cribl.Cloud and Cribl.Cloud Government.

Once you have the Client ID and Client Secret, send them as form fields in a request to https://criblgov-prod.okta.com/oauth2/ausfuanngyqh8CJ6c4h7/v1/token to retrieve the 24-hour Bearer token to use to authenticate subsequent API requests. The request includes these form fields:

• grant_type: The OAuth grant type. For API Credentials, the value is always client_credentials.
• client_id and client_secret: The Client ID and Client Secret from the API Credential. The Client ID and Client Secret are sensitive information and should be kept private, so the example request shows how to provide them as variables.
• audience: The audience configured for Cribl.Cloud Government in Okta. The value is always https://api.cribl-gov.cloud. This is not the URL to use for subsequent API requests, which require the appropriate base URL as shown in the API request example.

curl --request POST \
--url "https://criblgov-prod.okta.com/oauth2/ausfuanngyqh8CJ6c4h7/v1/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=${clientId}" \
--data-urlencode "client_secret=${clientSecret}" \
--data-urlencode "audience=https://api.cribl-gov.cloud"

As shown in the following example response, the JSON object in the response includes several attributes:

• token_type: The type of the token. In Cribl.Cloud Government and hybrid deployments, the value is always Bearer.
• expires_in: The number of seconds until the Bearer token expires. In Cribl.Cloud Government and hybrid deployments, Bearer tokens expire 24 hours (86400 seconds) after they are created. You are responsible for ensuring that your applications obtain a new Bearer token within the expiration window for each token.
• access_token: The Bearer token to use in the Authorization header for authentication in subsequent API requests.
• scope: In Cribl.Cloud Government and hybrid deployments, the value is always zeus_api_access. The authentication server grants this default scope for every API Credential token. The Permissions that you assigned to the API Credential still determine which API operations the Bearer token can perform.

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "abcdefg1234567890...exampleBearerToken",
  "scope": "zeus_api_access"
}

To use the Bearer token in subsequent API requests, include it in the Authorization header as shown in this control plane example:

curl --request GET \
--url "https://${workspaceName}-${organizationId}.cribl-gov.cloud/api/v1/m/${groupName}/system/inputs" \
--header "Authorization: Bearer abcdefg1234567890...exampleBearerToken" \
--header "Content-Type: application/json"

Authenticate in On-Prem Deployments ​

To authenticate using the API in on-prem deployments, send a request to the /auth/login endpoint. The response includes the Bearer token required for subsequent API requests.

The following example request demonstrates an /auth/login request. Replace the variables in the example request with your hostname, port, and login credentials (username and password). Your username and password are sensitive information and should be kept private, so the example request shows how to provide them as variables.

curl --request POST \
--url "https://${hostname}:${port}/api/v1/auth/login" \
--header "Content-Type: application/json" \
--data "{
  \"username\": \"${username}\",
  \"password\": \"${password}\"
}"

The response is a JSON object like the following example. The value of the token attribute in the response is the Bearer token:

{
  "token": "abcdefg1234567890...exampleBearerToken",
  "forcePasswordChange": false
}

To use the Bearer token in subsequent API requests, include it in the Authorization header, like this:

curl --request GET \
--url "https://${hostname}:${port}/api/v1/m/${groupName}/system/inputs" \
--header "Authorization: Bearer abcdefg1234567890...exampleBearerToken" \
--header "Content-Type: application/json"

Authenticate and Create HEC Tokens with Python ​

Cribl Solutions Engineering developed an example script that demonstrates how to use Python to authenticate to the Cribl API, make a simple POST request, and add a new HEC token. The script and instructions for usage are available in the py_hec_token_mgr GitHub repo.

To use the script, you’ll need:

• Python 3.
• The Python 3 Requests module (use brew or pip3 to install).
• A working, distributed Cribl Stream or Edge installation, with a configured Splunk HEC Source.
• An admin username and password.