> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization provisioning with API tokens

<Note>
  This feature is only available on Chainloop's platform [paid plans](https://chainloop.dev/pricing).
</Note>

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](/guides/deployment/guides/provisioning#instance-administrators) 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.

```bash theme={"dark"}
$ 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.

<Note>
  Instance-level tokens should be treated as highly sensitive credentials. Store them securely and rotate them regularly.
</Note>

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](/command-line-reference/cli-ee-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.

```sh theme={"dark"}
export CHAINLOOP_TOKEN=<token-contents>
```

Alternatively, you can use the `--token` flag to specify the token contents directly:

```sh theme={"dark"}
chainloop --token $TOKEN ...
```

### Creating organizations

With an instance-level token, you can create new organizations programmatically:

```sh theme={"dark"}
$ chainloop org create --name <org-name> ...
INF Organization "my-org" created!
```

<Info>
  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](/guides/deployment/guides/restrict-org-creation) for more details.
</Info>

### 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:

```sh theme={"dark"}
chainloop org member invitation create --org <org-name> --email <user-email> ...
```

See the [org member invitation reference](/command-line-reference/cli-ee-reference#chainloop-organization-member-invitation) for more details.

### Configuring CAS backends

You can also create and configure CAS (Content Addressable Storage) backends for any organization:

```sh theme={"dark"}
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](/command-line-reference/cli-ee-reference#chainloop-cas-backend-add) for more details.

## Security considerations

<Warning>
  Instance-level API tokens have broad permissions across all organizations. Follow these security best practices:
</Warning>

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

## Related guides

* [Automatic provisioning of user roles and groups](/guides/deployment/guides/provisioning) - Configure instance administrators and automatic user onboarding
* [Restrict organization creation to specific users](/guides/deployment/guides/restrict-org-creation) - Control who can create organizations