Skip to main content
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

CapabilityAllowed
List, get, create, update, delete pipelines in your groupYes
Read pipeline status, logs, metrics, destination-healthYes
Call Foundational, Streaming, CLI, or x402 APIsNo - use a regular API key
Sign in to the Platform UINo - use email/password or SSO
Manage billingNo - 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

StatusCauseFix
401 UnauthorizedHeader missing, malformed, or the key has been revoked.Confirm Authorization: Bearer <key> and that the key is still active on the Platform.
403 ForbiddenThe 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 FoundThe pipeline does not exist or has been deleted.Re-list with GET /platform/pipeline-api/.