API Keys

API keys are how machines authenticate to Clonit Cloud. A CI/CD pipeline, a nightly snapshot job, or any headless agent that can’t open a browser uses an API key to push and pull snapshots through the cloud.

The guiding principle:

Humans use clonit login. Machines use API keys.

Interactive clonit login is for people — it runs an OAuth 2.0 device grant against the sign-in service and stores a short-lived session that refreshes itself. Automation has no browser and no person to approve a prompt, so it carries a long-lived API key instead.

Two kinds of keys

Every key belongs to an organization, but a key is scoped one of two ways.

Scope	Acts as	Best for
Org-level	The whole organization (full org access)	CI/CD and shared automation
Per-user	The user it was minted for	A specific person’s agent / laptop

Org-level keys (the CI/CD path)

An org-level key has full access to its organization’s snapshots, independent of any single person. It keeps working when employees come and go, which is exactly what you want for a build server or a scheduled job. An organization admin (or owner) creates these.

Per-user keys

A per-user key acts as the user it was minted for: it sees and shares only the snapshots that user is allowed to under their org role and group shares. It is the natural credential for one person’s agent.

You usually never create a per-user key by hand. When you run clonit login, Clonit automatically provisions a per-user agent key for you and stores it so push and pull work immediately (see Where your key lives below). Each user has at most one of these agent keys per organization; signing in again rotates it.

Permissions: pull and push

A key carries a permission set that gates which snapshot operations it may perform:

Permission	Allows
`pull`	Downloading snapshots from cloud-managed storage
`push`	Uploading snapshots to cloud-managed storage

A key may grant pull, push, or both. This lets you hand a build pipeline a push-only key (it can publish snapshots but never download production data back out) or a deploy job a pull-only key.

Permissions never widen what a key can reach — they only narrow it. A per-user key is still bounded by that user’s org role and shares; an org-level key is bounded by the organization. Roles are covered in Organizations & Teams.

What a key looks like

A Clonit Cloud API key is a single opaque string that begins with clt_:

clt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

The cloud only ever stores a hash of the key plus its first few characters (the prefix, e.g. clt_a1b2c3d4) so it can show you which key is which in a list.

Where your key lives

Once you have a key, the agent reads it from cloud.api_key. There are two ways to provide it.

In the config file (clonit config edit):

cloud:
  url: "https://cloud.clonit.ai"
  api_key: "clt_your_api_key_here"

As an environment variable (preferred in CI and containers):

export CLONIT_CLOUD__URL="https://cloud.clonit.ai"
export CLONIT_CLOUD__API_KEY="clt_your_api_key_here"

The prefix is CLONIT_ and nested keys use __ (double underscore). See Configuration for full precedence rules.

Creating a key for CI/CD

Org-level keys for automation are created by an organization admin in the Clonit web UI. Start the agent’s web interface and open the cloud settings:

clonit serve

Then, from the Settings → Organization → API Keys area:

Choose Create API key.
Give it a clear name — name keys after where they run (github-actions-push, nightly-pull-runner) so a leaked key is easy to trace and revoke.
Select its permissions (pull, push, or both). Grant the least it needs.
Copy the full key now — it is shown only once.

Drop the copied key into your pipeline’s secret store and expose it to the agent as CLONIT_CLOUD__API_KEY (or set cloud.api_key in that environment’s config).

Example: a push-only CI job

# In your CI environment (key pulled from the CI secret store):
export CLONIT_CLOUD__URL="https://cloud.clonit.ai"
export CLONIT_CLOUD__API_KEY="$CLONIT_PUSH_KEY"   # a push-only org-level key

clonit build mydb            # create the snapshot
clonit push --cloud mydb     # publish it to the org's managed storage

The matching deploy job elsewhere uses a separate pull-only key with clonit pull --cloud. See Push & Pull via Cloud for the full data-plane workflow.

Rotating a key

There is no in-place “regenerate” — rotation is create new, then delete old, which guarantees the old secret stops working the moment you’re done:

Create a fresh key with the same name pattern and permissions.
Update the secret in your CI / secret manager to the new key.
Confirm the pipeline still pushes/pulls successfully.
Delete the old key.

Rotate on a schedule, and immediately if a key is ever exposed (committed to a repo, pasted in a log, shared in chat).

For a per-user agent key, rotation is even simpler: run clonit login again. That revokes your previous agent key and provisions a new one in one step.

Deleting a key

Deleting a key revokes it immediately — any agent or job still using it will fail to authenticate on its next cloud call. Delete keys from the same Settings → Organization → API Keys area where you created them. Deleting org keys requires the admin role.

Delete a key when:

A pipeline or machine is decommissioned.
A key may have leaked.
You’ve finished rotating to a replacement.

Quick reference

Question	Answer
Who creates org-level keys?	An organization admin or owner
Where?	The web UI (`clonit serve` → Settings → Organization → API Keys)
What does the agent read?	`cloud.api_key` (or `CLONIT_CLOUD__API_KEY`)
Key format	A `clt_…` string; only the prefix is shown after creation
Permissions	`pull`, `push`, or both (none = all)
Rotate	Create new → switch → delete old (or re-run `clonit login` for a user key)
Humans	Use `clonit login`, not a hand-made key