On This Page

Home / Cribl as Code/ Cribl SDKs (Preview)/Authenticate with the Cribl SDKs (Preview)

Authenticate with the Cribl SDKs (Preview)

Preview Feature

The Cribl SDKs are Preview features that are still being developed. We do not recommend using them in a production environment, because the features might not be fully tested or optimized for performance, and related documentation could be incomplete.

Please continue to submit feedback through normal Cribl support channels, but assistance might be limited while the features remain in Preview.

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 Transport Layer Security (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.

The code examples in this topic demonstrate how to authenticate using the Cribl Python SDK for the control plane. Authentication examples are also available for the Cribl Go and TypeScript SDKs for the control plane.

Token Management

All Cribl API requests require you to authenticate with a Bearer token, except health.get when the client uses the global context and auth.tokens.get. In Cribl, Bearer tokens are JSON Web Tokens (JWTs).

You must include a valid Bearer token in the appropriate configuration when initializing your SDK client. The Bearer token verifies your identity and ensures secure access to the requested resources. The SDKs automatically manage the Authorization header for all subsequent requests once properly authenticated.

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

In Cribl.Cloud and hybrid deployments, use the client_oauth security scheme. The SDK uses the OAuth credentials that you provide to obtain a Bearer token and refresh the token within its expiration window using the standard OAuth2 flow.

In on-prem deployments, use the bearer_auth security scheme. The SDK uses the username/password credentials that you provide to obtain a Bearer token. Automatically refreshing the Bearer token within its expiration window requires a callback function as shown in the authentication example.

Authenticate in Cribl.Cloud and Hybrid Deployments

To authenticate for the control plane or management plane SDKs, first create an API Credential. The API Credential provides a Client ID and Client Secret, which you must provide in your authentication configuration.

You can create API Credentials with the api_credentials.create method in the Cribl Python SDK for the management plane. However, you must first create the initial API Credential manually in the Cribl UI. This is necessary because you need the CLIENT_ID and CLIENT_SECRET for an existing API Credential to create an authenticated SDK client to make subsequent requests, including 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. Toggle to disable the Credential if needed.

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

  8. (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.

  9. 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.

Next, configure authentication as shown in the following example. Replace the placeholder values in the example request with your OAuth credentials (the Client ID and Client Secret from the API Credential). Base URLs are initialized during authentication, so make sure to replace the placeholder values for your Organizaton ID and Workspace name as well.

If you prefer, you can create and save an .env file to keep sensitive information out of your source code.

Python Control Plane SDK Authentication Example (Cribl.Cloud and Hybrid)Python Management Plane SDK Authentication Example (Cribl.Cloud)

Authenticate in On-Prem Deployments

To authenticate in on-prem deployments, provide your username and password in the authentication request. Base URLs are initialized during authentication, so make sure to replace the placeholder value for your server URL as well. Your username and password are sensitive information and should be kept private.

On-prem deployments use a callback function to refresh the Bearer token when it expires.

If you prefer, you can create and save an .env file to keep sensitive information out of your source code.

Python SDK Authentication Example (On-Prem)