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. To create an API key:

1. Navigate to the Settings page using the settings button located in the bottom left corner

2. Select "Access" from the sidebar menu

3. Click on the "API Keys" tab

4. Create a new API Key, ensuring you assign it to a service account that is bound to the appropriate RBAC policy

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>' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --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.

API Keys vs Ingestion Keys

	Ingestion Key	API Key
Primary purpose	Write data (ingest)	Read data / manage resources via REST
Permissions capabilities	Write‑only + optional remote‑config read	Mirrors service‑account RBAC
Visibility after creation	Always revealable	Shown once only
Typical lifetime	Tied to integration lifecycle	Rotated for CI/CD automations
Revocation effect	Data stops flowing immediately	API calls fail

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.