Set Up an API Key for CI/CD

API keys are the right credential for any non-interactive caller, including CI pipelines, Terraform, deployment tooling, and scheduled jobs.

For the full schema, see Reference: API keys.

Generate a key

Generate the key in the console as a tenant admin. Create a key with a clear display name, the narrowest role that works, and an expiry when the access should be temporary.

Field	Required	Description
`displayName`	Yes	Human-readable name used when listing or revoking the key later.
`role`	Yes	`admin` or `readonly`. Pick the minimum that the pipeline needs.
`expiresAt`	No	RFC3339 timestamp. Set this for contractor access or any temporary key.

The raw key value is prefixed with kupe_ and is only shown once. The platform stores a hash, not the key itself. If you lose it, revoke the key and generate a new one.

Store the key securely

GitHub Actions: add as a repository or organisation secret (Settings → Secrets and variables → Actions), then reference as ${{ secrets.KUPE_API_KEY }}
GitLab CI: add as a CI/CD variable, mark it Masked and Protected
Other systems: use the platform’s first-party secret store. Never commit keys to git.
Pass it to curl via an env var, never inline:
Terminal window
```
curl -H "Authorization: Bearer $KUPE_API_KEY" ...
```

List existing keys

Returns metadata only — never the raw key. Use this to find a key by its displayName before revoking.

export KUPE_TENANT="<tenant>"

curl -s \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/apikeys" \
  | jq

Revoke a key

export ADMIN_API_KEY="kupe_..."

curl -X DELETE \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/apikeys/ak-7f3b2c1d"

Revocation takes effect immediately. There is no grace period.

Rotation pattern

To rotate a CI/CD key without downtime:

Generate a second key with the same displayName (suffixed -new)
Update the CI/CD secret to the new key
Trigger a pipeline run to confirm the new key works
Revoke the old key

Permissions

Creating, listing, and revoking keys all require the admin role. A readonly member or key cannot manage API keys.