# 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

### 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:

```sh
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.