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 free Live requests or payment setup. Every key, Test or
Live, needs a verified workspace-owner email: you confirm it with the code we
email you at signup. 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 |
| Empty balance after the free Live requests | 402 | BALANCE_EMPTY |
| 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.