These docs are for Cribl Api 4.17 and are no longer actively maintained.
See the latest version (4.18).
Create API Credentials with the Cribl SDK
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.
These code examples demonstrate how to use the Cribl Python SDK for the management plane 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 you need the CLIENT_ID and CLIENT_SECRET for an existing API Credential to create an authenticated SDK client for subsequent requests, including requests to create new API Credentials. 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 Example
The code example uses Bearer token authentication. Read the authentication documentation for the SDKs to learn how to configure authentication. The Bearer token must be granted Organization Owner or Admin Permissions.
Replace the variables in the example with the corresponding information for your Cribl deployment.
The resource configurations in the example does 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.
The comment block at the beginning of the example includes instructions for using the new API Credential for subsequent SDK requests.
"""
Create a Cribl.Cloud API Credential Example (Organization Admin)
This example demonstrates how to create a new API Credential with the Admin Role on
an Organization. The Admin Role is effective across the Organization, including
all Workspaces and all products (no Workspace or product matrix is required).
1. Create an SDK client with OAuth2 client credentials using the client_oauth security scheme.
2. Create a new API Credential with Organization-level Admin and an optional IP allowlist
to restrict API access for the API Credential to the specified IPv4 CIDR range.
Prerequisites: Replace the placeholder values for ORG_ID, CLIENT_ID, and CLIENT_SECRET with
your Organization ID and the Client ID and Secret for an existing API Credential. You need
these values for an existing API Credential to authenticate this script.
To get the Client ID and Secret for an existing API Credential, follow the steps at
https://docs.cribl.io/cribl-as-code/sdks-auth/#sdks-auth-cloud.
To use the new API Credential for later SDK calls, you need its client_id and client_secret.
When create succeeds, the object returned from api_credentials.create(...) includes client_id,
client_secret, name, and the other APICredentialCreateResponseSchema fields. Read the new
client_secret as response.client_secret on that same object. The API returns client_secret
only in the create response (not in GET responses). Do not print or log the client_secret.
Pass the client_id and client_secret for the new API Credential into client_oauth when you
construct the CriblMgmtPlane client for later SDK calls.
Client Secrets are sensitive information and should be kept private.
"""
from cribl_mgmt_plane import CriblMgmtPlane, errors, models
# Cribl.Cloud configuration: Replace the placeholder values
CLIENT_ID = "your-client-id" # Replace with the OAuth2 Client ID for an existing API Credential
CLIENT_SECRET = "your-client-secret" # Replace with the OAuth2 Client Secret for an existing API Credential
ORG_ID = "your-org-id" # Replace with the Organization ID
# Token URL and audience for Cribl.Cloud OAuth2
TOKEN_URL = "https://login.cribl.cloud/oauth/token"
AUDIENCE = "https://api.cribl.cloud"
IP_ALLOWLIST = ["203.0.113.0/24"] # Replace with your IPv4 CIDR range.
def main():
# Create authenticated SDK client with OAuth2
with CriblMgmtPlane(
security=models.Security(
client_oauth=models.SchemeClientOauth(
client_id=CLIENT_ID,
client_secret=CLIENT_SECRET,
token_url=TOKEN_URL,
audience=AUDIENCE,
),
),
) as cmp_client:
try:
response = cmp_client.api_credentials.create(
organization_id=ORG_ID,
name="Auto-Manage-WorkspacesAuto-Manage-Workspaces",
description="Used for automated Workspace management",
enabled=True,
roles={"organization_role": models.OrganizationRole.ADMIN},
ip_allowlist=IP_ALLOWLIST,
)
print(
"✅ Created API Credential "
f"name={response.name!r} client_id={response.client_id!r}" # type: ignore
)
except errors.CriblMgmtPlaneError as e:
if e.status_code == 401:
print("⚠️ Authentication failed! Check your CLIENT_ID and CLIENT_SECRET.")
elif e.status_code == 429:
print("⚠️ Uh oh, you've reached the rate limit! Try again in a few seconds.")
else:
print(f"❌ Something went wrong: {e.message}")
if __name__ == "__main__":
main()
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
mainWorkspace. - Editor on all Cribl products in the
mainWorkspace.
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 Python SDK for the management plane 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.
The comment block at the beginning of the example includes instructions for using the new API Credential for subsequent SDK requests.
"""
Create a Cribl.Cloud API Credential Example (Organization and Workspace User, Product Editor)
This example demonstrates how to create a new API Credential with the User Role on
an Organization and a Workspace, and the Editor Role on all Products.
1. Create an SDK client with OAuth2 client credentials using the client_oauth security scheme.
2. Create a new API Credential with:
- User Role on the Organization and the `main` Workspace.
- Editor on all Cribl products in the `main` Workspace.
- An optional IP allowlist to restrict API access for the API Credential to the specified IPv4 CIDR range.
Use the returned client_id and client_secret for the new API Credential in subsequent
requests. The client_secret is only returned on create.
Prerequisites: Replace the placeholder values for ORG_ID, CLIENT_ID, and CLIENT_SECRET with
your Organization ID and the Client ID and Secret for an existing API Credential. You need
these values for an existing API Credential to authenticate this script.
To get the Client ID and Secret for an existing API Credential, follow the steps at
https://docs.cribl.io/cribl-as-code/sdks-auth/#sdks-auth-cloud.
To use the new API Credential for later SDK calls, you need its client_id and client_secret.
When create succeeds, the object returned from api_credentials.create(...) includes client_id,
client_secret, name, and the other APICredentialCreateResponseSchema fields. Read the new
client_secret as response.client_secret on that same object. The API returns client_secret
only in the create response (not in GET responses). Do not print or log the client_secret.
Pass the client_id and client_secret for the new API Credential into client_oauth when you
construct the CriblMgmtPlane client for later SDK calls.
Client Secrets are sensitive information and should be kept private.
"""
from cribl_mgmt_plane import CriblMgmtPlane, errors, models
# Cribl.Cloud configuration: Replace the placeholder values
CLIENT_ID = "your-client-id" # Replace with the OAuth2 Client ID for an existing API Credential
CLIENT_SECRET = "your-client-secret" # Replace with the OAuth2 Client Secret for an existing API Credential
ORG_ID = "your-org-id" # Replace with the Organization ID
# Token URL and audience for Cribl.Cloud OAuth2
TOKEN_URL = "https://login.cribl.cloud/oauth/token"
AUDIENCE = "https://api.cribl.cloud"
IP_ALLOWLIST = ["203.0.113.0/24"] # Replace with your IPv4 CIDR range.
# All product identifiers exposed by this SDK for workspace-scoped roles.
ALL_CRIBL_PRODUCTS = (
models.Product.STREAM,
models.Product.SEARCH,
models.Product.LAKE,
models.Product.EDGE,
)
def main():
main_workspace_editor_products = [
models.ProductRoleSchema(product=product, role=models.Role.EDITOR)
for product in ALL_CRIBL_PRODUCTS
]
roles = models.APICredentialRolesSchema(
organization_role=models.OrganizationRole.USER,
workspaces=[
models.WorkspaceRoleSchema(
workspace_id="main",
workspace_role=models.WorkspaceRole.USER,
products=main_workspace_editor_products,
),
],
)
# Create authenticated SDK client with OAuth2
with CriblMgmtPlane(
security=models.Security(
client_oauth=models.SchemeClientOauth(
client_id=CLIENT_ID,
client_secret=CLIENT_SECRET,
token_url=TOKEN_URL,
audience=AUDIENCE,
),
),
) as cmp_client:
try:
response = cmp_client.api_credentials.create(
organization_id=ORG_ID,
name="Product-Editor",
description="Editor Role on all Cribl Products",
enabled=True,
roles=roles,
ip_allowlist=IP_ALLOWLIST,
)
print(
"✅ Created API Credential "
f"name={response.name!r} client_id={response.client_id!r}" # type: ignore
)
except errors.CriblMgmtPlaneError as e:
if e.status_code == 401:
print("⚠️ Authentication failed! Check your CLIENT_ID and CLIENT_SECRET.")
elif e.status_code == 429:
print("⚠️ Uh oh, you've reached the rate limit! Try again in a few seconds.")
else:
print(f"❌ Something went wrong: {e.message}")
if __name__ == "__main__":
main()
Store and Protect the Client Secret
When api_credentials.create succeeds, the returned object includes client_id and client_secret for the new API Credential. Pass them to SchemeClientOauth when you create a CriblMgmtPlane client for the new credential as described in Authenticate in Cribl.Cloud and Hybrid Deployments.
The api_credentials.list and api_credentials.get methods do not return client_secret. Only the api_credentials.create response includes it. Save client_secret to your secret storage when you create a new API Credential or use automation to write it to a secrets manager. You cannot retrieve the client_secret later.
The client_secret is sensitive information and should be kept private.
Rotate API Credentials
On a CriblMgmtPlane client, api_credentials exposes create, list, get, update, and delete.
Those operations wrap the same routes documented in the management plane API Reference.
To rotate with the SDK:
Call
api_credentials.createand get the newclientIdandclientSecretfrom the response.Replace the old
clientIdandclientSecretvalues with the new values wherever they are used.In Python, pass the new
client_idandclient_secrettoSchemeClientOauthwhen you construct the nextCriblMgmtPlaneclient.Confirm that the old
clientIdandclientSecretvalues are replaced and validate the new values.Call
api_credentials.deleteto delete the old 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.