> ## 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 scoped to the GoldRush Pipeline REST API. They are required to create, update, and delete pipelines outside the Platform UI.

A **ServiceKey** is a programmatic credential issued from the GoldRush Platform that authenticates against the [Pipeline REST API](/api-reference/pipeline-api/list-pipelines). Regular GoldRush API keys are read-only and are rejected by the Pipeline REST endpoints.

## Why a separate credential?

Pipelines are stateful infrastructure - creating one provisions a worker, opens a connection to your destination, and starts consuming data. We use a different credential type so that:

1. **Read-only API keys** (which may be embedded in client-side code, CLI scripts, or shared between teammates) cannot accidentally create, modify, or delete pipelines.
2. **ServiceKeys** can be rotated independently of the API keys your application already uses to call the Foundational and Streaming APIs.
3. Pipeline mutations are auditable - every CRUD 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 Pipeline REST request:

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

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

resp = requests.get(
    "https://api.covalenthq.com/platform/pipeline-api/",
    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/pipeline-api/", {
  headers: { Authorization: `Bearer ${process.env.GOLDRUSH_SERVICE_KEY}` },
});
const body = await resp.json();
console.log(body);
```

## Scope and permissions

| Capability                                                | Allowed                        |
| --------------------------------------------------------- | ------------------------------ |
| List, get, create, update, delete pipelines in your group | Yes                            |
| Read pipeline status, logs, metrics, destination-health   | Yes                            |
| Call Foundational, Streaming, CLI, or x402 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 pipelines 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 your pipelines still respond (`GET /platform/pipeline-api/`).
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.                                                            |
| `403 Forbidden` (with valid ServiceKey) | The pipeline belongs to a different group.                      | Confirm the `pipeline_id` belongs to your group.                                          |
| `404 Not Found`                         | The pipeline does not exist or has been deleted.                | Re-list with [`GET /platform/pipeline-api/`](/api-reference/pipeline-api/list-pipelines). |