Base URLs

​

The base URL is the root address for making requests to the Cribl API. Follow the format examples in this section to construct the base URL for your Cribl deployment.

To compose the complete URL for a request to a specific endpoint, append the endpoint path that is listed in the API Reference to your base URL (for example, https://myapp.goatfarm.com:3000/api/v1/m/devgroup/routes).

Base URLs on Cribl.Cloud

​

On Cribl.Cloud, the base URL format for Cribl Stream, Edge, and Lake endpoints is:

https://${workspaceName}-${organizationId}.cribl.cloud/api/v1

For requests that are specific to a certain Worker Group or Fleet, the base URL includes /m and the name of the Worker Group or Fleet:

https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/${groupName}

For licenses that are limited to a single Worker Group, the groupName is always default.

For Cribl Search endpoints, the base URL includes /m and default_search:

https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search

Base URLs in Customer-Managed Deployments

​

Customers who manage their own single-instance deployments use the following base URL format:

https://${hostname}:${port}/api/v1

In Distributed deployments that are customer-managed, the base URL includes /m and the name of the Worker Group or Fleet:

https://${hostname}:${port}/api/v1/m/${groupName}

For licenses that are limited to a single Worker Group, the groupName is always default.

Data Format

​

Most endpoints in the Cribl API support JSON-formatted requests and responses in application/json or application/x-ndjson format.

Some endpoints support other data formats. For example, the /auth/slo/callback and /auth/sso/callback endpoints accept requests in application/x-www-form-urlencoded, and the /system/diag/download and /master/bundles/${groupName}/${version} endpoints return data in application/tar+gzip format.

The API Reference provides the data format for each endpoint’s requests and responses.

Request Size Limit

​

The size limit for requests to the Cribl API is 5 MB.

Authenticate to the API

​

Except for calls to the /auth/login and /health endpoints, all Cribl API requests require you to authenticate with a Bearer token. In Cribl, Bearer tokens are JSON Web Tokens (JWTs). You must include a valid Bearer token in the Authorization header of your API requests to verify your identity and access the requested resource.

The process for obtaining a Bearer token differs between Cribl.Cloud and customer-managed deployments, as described in this section.

Authenticate on Cribl.Cloud

​

To obtain a Bearer token on Cribl.Cloud, you must create an API Credential and then use the credential details in a request to https://login.cribl.cloud/oauth/token as shown in the example below. The response to your request includes the Bearer token.

To create an API Credential:

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 Role to use for defining Permissions for the Credential’s tokens.

   The Organization Permissions selector is available on certain plan/license tiers. Without a proper license, all tokens are granted the Admin Role.

   • If you choose the User Role, under Workspace Access, define the desired Permissions for specific Workspaces.

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

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 Owners and Admins can use to generate Bearer tokens.

To obtain a 24-hour Bearer token, run the following example request to https://login.cribl.cloud/oauth/token. Replace the variables in the example request with your API Credential’s Client ID and Client Secret.

curl -X POST '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"
}'

The response is a JSON object, like this example:

{
  "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"
}

The response includes the following 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. On Cribl.Cloud, Bearer tokens expire 24 hours (86400 seconds) after they are created. Admins are responsible for ensuring that their applications obtain a new Bearer token within each token’s expiration window.
• token_type: The type of the token. On Cribl.Cloud, the value is always Bearer.

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

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

Organization Owners and Admins can view, edit, and disable existing API Credentials. Only Owners can delete API Credentials.

Authenticate in Customer-Managed Deployments

​

To obtain a Bearer token in a customer-managed deployment, send a local authentication request to the /auth/login endpoint as shown in the example below.

If you’re using SSO/OpenID Connect Authentication, you must toggle Allow login as Local User on. You’ll need to be a Local user when you authenticate via the API.

To use https in the URL for your authentication request as shown in this example, you must configure Transport Layer Security (TLS). If you do not configure TLS, modify the example URLs to use http instead. Use http only for testing in development environments. In production, configure TLS and use https to secure your communications.

Run the following example request to obtain a Bearer token. Replace the variables in the example request with your hostname, port, and login credentials.

curl -X POST '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": "Bearer abcdefg1234567890...exampleBearerToken",
  "forcePasswordChange": false
}

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

curl -X GET 'https://${hostname}:${port}/api/v1/system/inputs' \
--header 'Authorization: Bearer Bearer abcdefg1234567890...exampleBearerToken' \
--header 'Content-Type: application/json'

In customer-managed 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). Admins are responsible for ensuring that their applications obtain a new Bearer token within each token’s expiration window.

Authenticate and Create HEC Tokens with Python

​

Cribl Solutions Engineering developed an example script that demonstrates how 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.

HTTP Status Codes

​

The Cribl API can return the following HTTP status codes in response headers:

See the MDN Web Docs for more information about HTTP status codes.