Skip to main content
This feature is only available on Chainloop’s platform paid plans.
Chainloop Enterprise Edition provides instance-level API tokens that enable automated organization provisioning workflows. These tokens allow administrators to programmatically create and configure organizations across the entire Chainloop instance.

​
Overview

Instance-level API tokens are designed for automation scenarios where you need to:
  • Provision new organizations programmatically
  • Invite members to any organization in the instance
  • Configure CAS backends for organizations
This is particularly useful for:
  • Multi-tenant deployments where organizations need to be created on-demand
  • Integration with external provisioning systems (e.g., customer onboarding workflows)
  • Infrastructure-as-code approaches to Chainloop configuration

​
Prerequisites

Before creating instance-level API tokens, ensure you have:
  • Instance administrator role: Your user account must have the instance admin role configured. See Automatic provisioning of user roles and groups for details on configuring instance administrators.
  • Chainloop CLI (EE): The Enterprise Edition CLI with the admin command available.

​
Creating an instance-level API token

Use the chainloop admin api-token create command to generate a token with instance-wide permissions. 
$ chainloop admin api-token create --name <token-name>
┌──────────────────────────────────────┬─────────┬─────────────┬─────────────────────┬────────────┬────────────┬──────────────┐
│ ID                                   │ NAME    │ DESCRIPTION │ CREATED AT          │ EXPIRES AT │ REVOKED AT │ LAST USED AT │
├──────────────────────────────────────┼─────────┼─────────────┼─────────────────────┼────────────┼────────────┼──────────────┤
│ 73126f23-5a92-4845-b1bc-15d3ba159255 │ token15 │             │ 05 Feb 26 16:34 UTC │            │            │              │
└──────────────────────────────────────┴─────────┴─────────────┴─────────────────────┴────────────┴────────────┴──────────────┘

Save the following token since it will not printed again:
...
Copy the token contents and store it securely.
Instance-level tokens should be treated as highly sensitive credentials. Store them securely and rotate them regularly.
The chainloop admin api-token create also supports an --expiration that can be used to set a custom expiration time for the token (e.g., --expiration 1h). Check the command line reference for more options.

​
Using instance-level tokens

Once you have an instance-level API token, you can use it to authenticate CLI commands that operate across the entire instance.

​
Authenticating with the token

The CLI will automatically use any token stored in the CHAINLOOP_TOKEN environment variable. 
export CHAINLOOP_TOKEN=<token-contents>
Alternatively, you can use the --token flag to specify the token contents directly: 
chainloop --token $TOKEN ...

​
Creating organizations

With an instance-level token, you can create new organizations programmatically: 
$ chainloop org create --name <org-name> ...
INF Organization "my-org" created!
The chainloop org create command is also available to users with the instance admin role through interactive authentication. See Restrict organization creation to specific users for more details.

​
Inviting members to organizations

Instance-level tokens can invite members to any organization in the instance. Note that the --org flag is required for this command, since the token has instance-wide permissions: 
chainloop org member invitation create --org <org-name> --email <user-email> ...
See the org member invitation reference for more details.

​
Configuring CAS backends

You can also create and configure CAS (Content Addressable Storage) backends for any organization: 
chainloop cas-backend add aws-s3 --access-key-id $ACCESS_KEY --secret-access-key $SECRET_ACCESS_KEY --bucket chainloop --endpoint http://localhost:9002 --name minio_local --default --org <org-name>
See the CAS backend reference for more details.

​
Security considerations

Instance-level API tokens have broad permissions across all organizations. Follow these security best practices:
  • Principle of least privilege: Only create instance-level tokens when truly needed for cross-organization operations.
  • Secure storage: Store tokens in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager).
  • Token rotation: Implement regular token rotation policies.
  • Audit logging: Monitor token usage through Chainloop’s audit logs.
  • Expiration: Set appropriate expiration times based on your security requirements.