Authentication
Authenticate every request with an API key in the Authorization header.
Authenticate with a bearer token: send your API key in the Authorization
header on every request. There is no OAuth flow and no session handling.
curl "https://api.openhandle.dev/v1/instagram/profiles/@northstar_forge_test" \
-H "Authorization: Bearer $OPENHANDLE_TEST_KEY"API keys
- Create and revoke keys in the dashboard under API Keys.
- The full secret is shown once at creation. We store only a hash and cannot show it again.
- Keys belong to your workspace. Usage from every key bills to the same workspace.
- Rotate by creating a new key, deploying it, and revoking the old one. Revocation is immediate.
Test and Live keys
Test keys start with oh_test_; Live keys start with oh_live_. The key
environment is immutable and selects the data path. Public requests have no
environment header, parameter, or body field that can override it.
Existing legacy oh_ keys remain Live keys.
Test keys use deterministic synthetic data and record a $0.000 actual charge.
They work without email verification, free Live requests, or payment setup.
Creating and using a Live key requires a verified workspace-owner email. Every
new verified workspace starts with 100 one-time free Live requests; after those,
Live uses normal billing. See Test API keys.
Failure modes
| Situation | Status | Error code |
|---|---|---|
| Missing or invalid key | 401 | UNAUTHENTICATED |
| Workspace-owner email is not verified | 403 | EMAIL_VERIFICATION_REQUIRED |
| No payment method after the free Live requests | 402 | PAYMENT_METHOD_REQUIRED |
| Workspace billing suspended | 402 | BILLING_SUSPENDED |
| Rate limit exceeded | 429 | RATE_LIMITED |
See envelope and errors for the full error catalog and the retry rules.
Keep keys secret
Call the API from your backend. Never ship an API key in a browser bundle or a mobile app: anyone can extract it and spend your budget.