Authentication
Tripswitch uses different credentials for different jobs. Most users only need project keys and an ingest secret.
Quick Reference
Each credential type has a distinct prefix. If you see an auth error, check that you're using the right one.
| Prefix | Type | Scope | Use For |
|---|---|---|---|
eb_pk_ |
Project Key | Single project | Runtime (state queries, SSE) |
| None (64-char hex string) | Ingest Secret | Single project | Ingestion integrity |
eb_admin_ |
Admin Key | Entire org | Management and automation |
Two Different Jobs
Runtime (Your App)
Project Key + Ingest Secret
Your application needs to send samples and check breaker state.
These credentials are scoped to a single project.
- Send metrics via HMAC-signed requests
- Query breaker state before making calls
- Subscribe to state changes via SSE
Management (Automation)
Admin Key
Your CI/CD pipeline or admin tooling needs to create projects and configure breakers.
These credentials work across your entire org.
- Create and delete projects
- Configure breakers and routers
- Manage API keys
These are fundamentally different use cases, not just different permission levels. Don't use admin keys in your application code.
For Most Users: Project Keys + Ingest Secret
If you're integrating Tripswitch into your application, this is what you need.
Where to Find Them
Each project has its own keys. You'll see:
-
Project Key (
eb_pk_...) — for querying breaker state - Ingest Secret (64-char hex string) — for signing sample data
Using the Project Key
Pass it as a Bearer token when checking breaker state:
GET /v1/projects/:project_id/breakers/:breaker_id/state
Authorization: Bearer eb_pk_abc123...
What Project Keys Can Do
- Read Breaker State
- Batch Breaker State
- Read Project Status
- SSE Subscription
Using the Ingest Secret
The ingest secret signs your sample payloads via HMAC. It's not sent directly — you compute a signature.
POST /v1/projects/:project_id/ingest
x-eb-timestamp: 1705123456789
x-eb-signature: v1=<hmac_sha256(secret, "timestamp.body")>
x-eb-timestamp header must be within
5 minutes of server time (milliseconds since epoch). This prevents replay attacks.
For Automation: Admin Keys
Admin keys are for CI/CD pipelines, infrastructure-as-code, and admin tooling. Most users don't need these.
Where to Find Them
Using an Admin Key
Pass it as a Bearer token for management operations:
POST /v1/projects
Authorization: Bearer eb_admin_xyz789...
Content-Type: application/json
{"name": "my-service", "slug": "my-service"}
What Admin Keys Can Do
- Create Project
- List Projects
- Delete Project
- Update Project
- Manage Breakers
- Manage Routers
- Manage Notification Channels
- Create Project Keys
- Revoke Project Keys
- Rotate Ingest Secret
- View Events
What Admin Keys Cannot Do
- SSE Subscription
- Sample Ingestion
Admin keys are org-wide credentials. Treat them like root access — store in a secrets manager, don't commit to repos.
Rotating Ingest Secrets
Ingest secrets support graceful rotation with a 24-hour overlap window.
- Call POST /v1/projects/:project_id/ingest_secret/rotate with admin key
- Response contains new ingest_secret
- Both old and new secrets accepted during grace period
- After grace period, only new secret works
- Update your application with new secret before grace expires
During the grace period, both old and new secrets are accepted. This lets you roll out the new secret across your fleet without downtime.
Common Mistakes
"I put my admin key in the SDK and it doesn't work"
Admin keys (eb_admin_) don't work for SSE subscriptions or sample ingestion.
Use a project key (eb_pk_) and ingest secret instead.
"I put my project key in my Terraform config"
Project keys can't create projects or manage breakers.
Use an admin key (eb_admin_) for infrastructure automation.
"Where's my ingest secret?"
The ingest secret is separate from the project key. Find both under Project Settings → SDK Keys.
"Auth fails but my key looks right"
Check the prefix. eb_pk_ vs eb_admin_ endpoints are different.
Also verify you're hitting the correct project ID in the URL.
Error Responses
When authentication fails, the API returns these error messages to help you diagnose the issue.
Admin Key Errors
| Status | Message | Cause |
|---|---|---|
| 401 | missing authorization header |
No Authorization header provided |
| 401 | invalid API key |
Key doesn't exist or has wrong prefix |
Project Key Errors
| Status | Message | Cause |
|---|---|---|
| 401 | missing authorization header |
No Authorization header provided |
| 401 | invalid API key |
Key doesn't exist or has wrong prefix |
| 403 | API key does not have access to this project |
Key belongs to a different project |
| 404 | not found |
Project ID doesn't exist |
Ingest (HMAC) Errors
All ingest auth failures return generic "unauthorized" to avoid leaking information.
Use the hints below to debug:
| Status | Likely Cause | How to Debug |
|---|---|---|
| 401 | Missing signature header | Check x-eb-signature header is present |
| 401 | Signature doesn't match | Verify HMAC computation and secret |
| 401 | Timestamp outside 5-minute window | Timestamp must be within 5 minutes of server time |
| 401 | Project ID doesn't exist | Project ID in URL doesn't exist |
Security Notes
- Ingest secrets are sensitive. They sign sample data. Keep them server-side only.
- Project keys are less sensitive but still shouldn't be exposed client-side. They're read-only but reveal breaker state.
- Admin keys are highly sensitive. They can delete projects and revoke access. Store in a secrets manager.
- Rotate keys immediately if you suspect compromise. Ingest secrets support graceful rotation with a 24-hour overlap window.