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. 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.
2. Open your account settings and select Service Keys.
3. Click Create Service Key, give it a name, and copy the value shown.

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.

Using a ServiceKey

Send the key as a bearer token on every Pipeline REST request:

curl https://api.covalenthq.com/platform/pipeline-api/ \
  -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY"

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())

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.

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

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/.