Skip to content

API Keys

API keys provide non-interactive authentication for scripts, automation, and service-to-service integrations. Each key is associated with one or more roles that determine what it can do.

One-time disclosure

The full secret value of an API key is returned only once, at the moment the key is created. After that, only the key prefix is visible. JIM stores only a SHA-256 hash of the key; the plaintext is never persisted, and there is no way to recover it.

If you lose the secret, you must delete the key and create a new one.

Prefix

Every key begins with jim_ for easy identification in logs and configuration files, followed by a random secret. Only the prefix is shown after creation, so you can identify which key is in use without exposing its secret.

Name and description

Unlike the prefix and secret, which are fixed at creation, the Name and Description can be edited at any time from the key's Details tab in the admin portal.

Expiry

Keys can be created with an absolute expiry date or with no expiry. Expired keys are rejected automatically and need to be replaced.

For production integrations, prefer keys with an expiry that aligns with your rotation policy (e.g. 90 or 180 days), so rotation is forced rather than relying on operational discipline.

Enabled flag

A key can be temporarily disabled without deleting it. Disabling revokes its access immediately while preserving its history (creation, last use, source IP). Re-enabling restores access. Use this when you want to suspend a key while you investigate, without losing the audit trail.

Roles

A key carries the permissions of its assigned roles. Almost all endpoints currently require the Administrator role; future role granularity will let you mint narrower keys for specific integrations.

Last-used tracking

JIM records the timestamp and source IP of each successful authentication. This is useful for spotting unused keys (good rotation candidates) and unexpected callers (potential compromise indicators).

Change history

Every change to an API key is recorded in configuration change history: creating, editing, enabling, disabling, or deleting a key captures a versioned snapshot of its metadata (name, description, key prefix, expiry, enabled state, infrastructure flag, and Role assignments) alongside who made the change, when, and an optional reason. The key secret is never captured in any form, not even a hash: JIM stores only the SHA-256 hash used for authentication on the key itself, and that hash is not part of the change history payload. Last-used tracking (timestamp and source IP) is operational state, not configuration, so it is not part of the history either.

Open a key's history from the Changes tab on its detail page, or retrieve it with Get-JIMConfigurationChangeHistory -Type ApiKey or the REST API. The optional "Reason for change" prompt appears when creating, editing, or deleting a key in the admin portal; automation can pass the same reason via -ChangeReason on the API key write cmdlets.

Common workflows

Issuing a key for a CI/CD integration:

  1. Create the key with a meaningful name (for example "GitHub Actions deploy"), an expiry consistent with your rotation policy, and the role(s) it needs
  2. Capture the full key from the create response and store it in your secret manager immediately; you will not be able to retrieve it again
  3. Configure the integration to send the key in the X-Api-Key header on every request

Rotating a key:

  1. Create a new key with the same role(s) and a future expiry
  2. Roll the new key out to the consuming integration
  3. Once you've confirmed the new key is in use (check Last Used At), delete the old one

Suspending a key after a suspected leak:

  1. Disable the key immediately (faster than deletion if you might need to inspect history)
  2. Investigate
  3. Either re-enable, or delete and rotate

Manage API Keys

See also

  • API Authentication -- how keys are presented on requests, plus the alternative JWT Bearer flow
  • Roles -- the permission grants assigned to a key