API keys are the bearer tokens your CI and the GitHub Action wrapper use to authenticate against the portal. Each key belongs to a user, works independently of the login cookie, and can be revoked independently.
Creating a key
On /api-keys:
- Give it a name, freely chosen (up to 120 characters). Recommendation:
what the key does or where it lives, e.g.
acme-web-ci. You will see the name later in the overview and in the audit log. - Choose a lifetime: 30 days, 90 days, 1 year, or unlimited. 1 year is preselected. Shorter lifetimes are more secure but require more frequent rotation.
- Click Generate key.
Every key carries the read:rules scope, which covers reading your rules
and profiles and downloading bundles. Tick write:rules to also allow the
key to upload drafts with codecharter push; leave it off for read-only CI keys.
Administrators can additionally grant a key the register:engines scope for
release automation. The scopes of each key are shown in the key list.
Note: most CLI commands no longer need an API key at all — analyze, restore,
update, and verify authenticate with your installed codecharter.license, and
push falls back to it too. An API key is only required when you cannot ship a
license to the runner (then a write:rules key is needed for push).
Copying the plaintext value
Immediately after creation the portal shows the full plaintext of the key once, in a warning banner on the page. Copy it right away — we only store a hash, and the plaintext is gone as soon as you leave or reload the page.
Keys start with cgk_, and the key list shows the first 12 characters of
each key, so you can match a stored secret to its list entry later.
If you have lost the value: simply create a new key and revoke the old one. We cannot show you the value after the fact.
Storing the key in your CI
Save the copied value as a secret in your CI system. Details for each CI system are covered under API keys in secrets.
GitHub Actions quick reference:
Repo → Settings → Secrets and variables → Actions → New repository secret
Name: CODECHARTER_API_KEY
Value: <the plaintext value>
In the workflow:
- uses: bochmann-software/codeguard@v1
with:
api-key: ${{ secrets.CODECHARTER_API_KEY }}
Revoking a key
In the portal API key list, click Revoke next to the entry and confirm in the dialog that opens. From the next CI call onwards, the key returns 401 Unauthorized.
There is no "un-revoke" — if you made a mistake, simply create a new key.
Rotating a key
If a key is compromised, or a team member who may have seen the plaintext leaves, rotate it like this:
- Create a new key in the portal.
- In your CI system, update the secret variable (
CODECHARTER_API_KEY) to the new value. - Trigger a CI run to confirm the new key works.
- Revoke the old key.
Multiple keys may be active simultaneously, so the new key is usable immediately while the old one is still valid — this gives you a clean zero-downtime rotation window before you revoke the old one.
What a key can do
A key authenticates the CLI's portal calls: fetching and renewing the
short-lived license, downloading CLI release archives, the update and
push commands, verify with --against-portal, and the CI checks
endpoint. restore does not need an API key — it authenticates with the
short-lived license itself. analyze runs locally and takes no API key.
With CODECHARTER_API_KEY set in the environment, the CLI automatically
fetches and renews the short-lived license from the portal. The update,
push, and verify --against-portal commands take the key via their
--api-key option instead.
API keys cannot publish or draft rules or profiles: creating or editing drafts, publishing versions, and archiving are only available in a logged-in browser session in the portal. With respect to your rule and profile content, a key is strictly read-only.
Rate limits
Portal API requests are rate-limited per identity. Each API key has its own budget; requests from a logged-in browser session count against the user account instead. The defaults are:
- 60 GET requests per minute
- 10 write requests per minute (POST, PUT, PATCH, DELETE)
Reads and writes have separate budgets. The window is a fixed 60 seconds, starting with the first request; at the end of the window the full budget is available again. CLI release archive downloads and the short-lived license endpoint are not rate-limited.
When a budget is exhausted, the portal answers 429 Too Many Requests. The
response carries a Retry-After header with the number of seconds until the
window resets, and a JSON body that repeats the value in a retryAfter
field. Wait that long and retry.
In practice a CI run stays far below these limits — restore only makes a
handful of requests. If you do hit 429, the usual cause is many parallel
jobs sharing one key. Cache the downloaded CLI archive instead of
re-downloading it in every job, and cache the bundle directory
(.codecharter/cache/) keyed on the lockfile so repeated runs make no portal
calls at all — see Using portal profiles in CI.
Since every key has its own budget, separate keys for independent pipelines
also keep them from throttling each other.
What happens when the trial ends
When your subscription has expired, keys return 402 Payment Required on the next call. The key remains active but unusable. As soon as the subscription is running again, the key works again without any changes.
Audit
In the API key list you can see per key:
- Name and key prefix (the first 12 characters)
- When it was created
- When it was last used
- When it expires
- Current status (active / revoked / expired)
- Its scopes
You can rename a key directly in the list via the pencil icon (up to 120 characters). An expired key is rejected with 401, just like a revoked one.
If a key is never used, that is a signal to revoke it; if "last used" shows activity you do not expect, look more closely at where the key is deployed.
Multiple keys in parallel
Useful if you have different CI setups — for example one key for the main CI and a separate one for a build server in an isolated environment. This lets you revoke one without affecting the other.
There is currently no hard limit on keys per account.