Authenticate with the Cribl 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. 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 on Cribl.Cloud or in a customer-managed (on-prem or hybrid) deployment.

• On Cribl.Cloud, Bearer tokens are valid for 24 hours.

• 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).

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

For customer-managed 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 in the URL for a customer-managed authentication request as shown in the examples, 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.

Authenticate on Cribl.Cloud

​

To authenticate with the API on Cribl.Cloud, first create an API Credential. The API Credential provides a Client ID and Client Secret, which you need for a request to https://login.cribl.cloud/oauth/token to obtain a 24-hour Bearer token to authenticate subsequent API requests.

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 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, provide them in the body of a request to https://login.cribl.cloud/oauth/token:

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

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. On Cribl.Cloud, 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. On Cribl.Cloud, 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, like this:

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

Authenticate in Customer-Managed Deployments

​

To authenticate using the API in customer-managed 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.

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'

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.