Pipeline API Authentication

How authentication works for the GoldRush Pipeline API: platform login, API keys, and ServiceKeys.

The Pipeline API has three distinct credential types. Picking the right one matters - a regular GoldRush API key cannot create or manage pipelines, and a ServiceKey cannot call the Foundational, Streaming, CLI, or x402 APIs.

Credential types at a glance

Credential	What it authenticates	Scope	Where used
Platform login	A human user signing in to the GoldRush Platform UI.	Full account access for that user.	GoldRush Platform - sign in, billing, creating API keys and ServiceKeys.
API key	A read-only programmatic credential.	Read-only across Foundational, Streaming, CLI, x402. Cannot manage pipelines.	Authorization: Bearer <GOLDRUSH_API_KEY> on Foundational, Streaming, CLI, x402.
ServiceKey	A programmatic credential scoped to pipeline management.	Full CRUD on pipelines belonging to your group. Cannot call Foundational, Streaming, CLI, or x402.	Authorization: Bearer <service_key> on the Pipeline REST API.

API keys and ServiceKeys are not interchangeable. Sending a regular API key to a Pipeline REST endpoint returns 403 Forbidden. Sending a ServiceKey to a Foundational or Streaming endpoint also returns 403.

1. Platform login

You authenticate as a user with email/password (or SSO) to access the GoldRush Platform. The Platform is where you:

• Configure pipelines through the UI.
• Manage billing and your subscription.
• Create and rotate API keys.
• Create and rotate ServiceKeys.

Vibe Coders

$10/mo - Built for solo builders and AI-native workflows.

Teams

$250/mo - Production-grade with 50 RPS and priority support.

2. API keys (read-only)

A regular GoldRush API key is a read-only programmatic credential. It works against:

• Foundational API - REST queries for balances, transactions, NFTs, etc.
• Streaming API - GraphQL/WebSocket subscriptions and queries.
• CLI - all goldrush commands.
• x402 - pay-per-request proxy.

It does not work for the Pipeline REST API, and it does not authenticate platform login.

3. ServiceKeys (Pipeline CRUD)

A ServiceKey is a programmatic credential scoped specifically to pipeline management. Use it to:

• List, create, update, pause, resume, and delete pipelines via the REST API.
• Poll status, logs, metrics, and destination health.
• Drive pipeline configuration from CI/CD, infrastructure-as-code, or scripts.

ServiceKeys are issued from the GoldRush Platform and can be rotated or revoked at any time. See Service Keys for details.

Destination credentials

Destination credentials (database passwords, webhook tokens, S3 access keys) are part of your pipeline configuration, not an authentication mechanism for GoldRush itself. You provide them when creating or updating a pipeline:

destination:
  type: "postgres"
  url: "postgresql://your-host:5432/your-database"
  user: "${PG_USER}"
  password: "${PG_PASSWORD}"

Destination credentials are stored encrypted, injected at deploy time via environment variable interpolation, and masked as ****** when read back through the REST API. They are never exposed in logs or the UI after being set.

Because secrets read back as ******, never echo them back in a write. Use PATCH to rotate a secret by sending the new value in destination_config.

Error handling

Status	Cause	Resolution
401 Unauthorized	Missing or malformed Authorization header.	Send Authorization: Bearer <key>.
403 Forbidden (Pipeline REST)	The credential is a regular API key, not a ServiceKey.	Create a ServiceKey on the Platform and retry.
403 Forbidden (Foundational/Streaming)	The credential is a ServiceKey, not an API key.	Use your regular API key for read endpoints.
403 Forbidden (Pipeline REST, valid ServiceKey)	The ServiceKey does not have access to the requested pipeline.	Confirm the pipeline belongs to the same group as the key.
Destination credential failure	The pipeline cannot connect to your destination.	Check destination-health and logs.

For a complete guide to error codes, retry strategies, and debugging tips, see Error Handling & Troubleshooting.

FAQ

• Can I use the same key for all GoldRush products?

  • No. API keys cover the read-only products (Foundational, Streaming, CLI, x402). ServiceKeys cover the Pipeline REST API. Platform login is separate.

• Where do I create a ServiceKey?

  • On the GoldRush Platform, under your account settings. See Service Keys.

• How are destination credentials stored?

  • Encrypted at rest, injected at deploy time, masked as ****** on read. They are never exposed in logs or the UI after being set.

• Do I need to allowlist GoldRush IP addresses?

  • If your destination is behind a firewall, yes. Contact support for the current egress IP list.