API Keys

An API key in groundcover provides secure, programmatic access to the API on behalf of a service account. It inherits that account’s permissions and should be stored safely.

An API key in groundcover provides secure, programmatic access to the API on behalf of a service account. It inherits that account’s permissions and should be stored safely

Binding and Permissions

Each API key is tied to a specific service account. It inherits the permissions defined by that account’s RBAC policies. Optionally, the key can be limited to a subset of those policies for more granular access control. An API key can never exceed the permissions of its parent service account.

Creation and Storage

Only Admins can create or revoke API keys. When a key is created, its value is shown once—store it securely in a secret manager or encrypted environment variable. If lost, a new key must be issued.

Authentication and Usage

To use an API key, send it in the Authorization header as bearer token:

curl 'https://api.groundcover.com/api/k8s/v3/clusters/list' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  --data-raw '{"sources":[]}'

The key authenticates as the service account, and all API permissions are enforced accordingly.

API Key authentication will work using https://api.groundcover.com/ only.

Validity and Revocation

API keys do not expire automatically. Revoking a key immediately disables its access.

Scope of Use

API keys are valid only for requests to https://api.groundcover.com. They do not support data ingestion or Grafana integration—those require dedicated tokens.

Security Best Practices

Store securely: Use secrets managers like AWS Secrets Manager or HashiCorp Vault. Never commit keys to source control.

Follow least privilege: Assign the minimal required policies to service accounts and API keys. Avoid defaulting to admin-level access.

Rotate regularly: Periodically generate new keys, update your systems, and revoke old ones to limit exposure.

Revoke stale keys: Remove keys that are no longer in use or suspected to be compromised.