> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Keys

> ServiceKeys are programmatic credentials for privileged, account-level GoldRush Platform operations, such as reading your usage programmatically.

A **ServiceKey** is a programmatic credential issued from the GoldRush Platform that authenticates privileged, account-level operations — for example, reading your account usage programmatically via the `/platform/usage/` endpoint. ServiceKeys work across all GoldRush products.

A regular GoldRush API key (`cqt_…`) authenticates product **data** requests (Foundational, JSON-RPC, Hyperliquid, x402). A ServiceKey authenticates Platform **account** operations that act on your account itself, and is rejected on the data APIs — and vice versa.

## Why a separate credential?

Account-level operations touch data about your usage and account configuration. We use a distinct credential type so that:

1. **Read-only API keys** (which may be embedded in client-side code, CLI scripts, or shared between teammates) cannot read or change account-level data.
2. **ServiceKeys** can be rotated independently of the API keys your application already uses to call the data APIs.
3. Account operations are auditable — every action is attributed to the user who issued the ServiceKey.

## Creating a ServiceKey

1. Sign in to the [GoldRush Platform](https://goldrush.dev/platform/).
2. Open your account settings and select **Service Keys**.
3. Click **Create Service Key**, give it a name, and copy the value shown.

<Warning>
  The ServiceKey value is shown **once**, at creation. Store it in a secret manager (e.g. AWS Secrets Manager, GCP Secret Manager, 1Password, Vault). If you lose it, revoke the key and create a new one.
</Warning>

## Using a ServiceKey

Send the key as a bearer token on every request. For example, to read your account usage:

```bash theme={null}
curl https://api.covalenthq.com/platform/usage/ \
  -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY"
```

```python theme={null}
import os, requests

resp = requests.get(
    "https://api.covalenthq.com/platform/usage/",
    headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_SERVICE_KEY']}"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript theme={null}
const resp = await fetch("https://api.covalenthq.com/platform/usage/", {
  headers: { Authorization: `Bearer ${process.env.GOLDRUSH_SERVICE_KEY}` },
});
const body = await resp.json();
console.log(body);
```

## Scope and permissions

| Capability                                                       | Allowed                        |
| ---------------------------------------------------------------- | ------------------------------ |
| Read your account usage (`GET /platform/usage/`)                 | Yes                            |
| Perform account-level Platform operations exposed to ServiceKeys | Yes                            |
| Call the Foundational, JSON-RPC, Hyperliquid, or x402 data APIs  | No — use a regular API key     |
| Sign in to the Platform UI                                       | No — use email/password or SSO |
| Manage billing                                                   | No — use the Platform UI       |

ServiceKeys inherit the group of the user who created them. Two users in different groups cannot see each other's account data through the API, even if both have a ServiceKey.

## Rotation and revocation

Rotate a ServiceKey at any time by creating a new one and revoking the old one:

1. Create a new ServiceKey on the Platform.
2. Update your secret store / CI variables to use the new key.
3. Verify the new key works with a test request (`GET /platform/usage/`).
4. Revoke the old key on the Platform.

Revocation is immediate — subsequent requests with the revoked key return `401 Unauthorized`.

<Tip>
  Use a separate ServiceKey per environment (dev, staging, prod) and per CI system. This keeps the blast radius small if a key is leaked.
</Tip>

## Common errors

| Status             | Cause                                                           | Fix                                                                                     |
| ------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Header missing, malformed, or the key has been revoked.         | Confirm `Authorization: Bearer <key>` and that the key is still active on the Platform. |
| `403 Forbidden`    | The credential supplied is a regular API key, not a ServiceKey. | Create a ServiceKey and retry.                                                          |