Authentication

Every request must include an API key via the Authorization header. Keys come in two flavors: test mode for development and live mode for production.

API keys

Create and revoke keys at platform.tunelab.dev/keys.

Prefix	Mode	Credits	Rate limit	Use for
`tl_test_...`	test	Never charged	10 req/min	Local dev, CI, examples
`tl_live_...`	live	Charged on miss	Per plan tier	Production traffic

✓

Test keys return deterministic responses.
The same request always returns the same JSON, so you can snapshot-test your integration without burning credits.

Sending the header

curl https://api.tunelab.dev/v1/resolve/spotify:2WfaOiMkCvy7F5fcp2zZ8L \
  -H "Authorization: Bearer tl_live_xxx"

Security best practices

Never commit keys to source control. Use environment variables.
Rotate keys if leaked. Old keys are revoked instantly on replacement.
Don't embed keys in client-side code. Proxy API calls through your backend.
Use test keys in public code samples and documentation. They leak safely.

Error responses

Status	Error code	Cause
`401`	`unauthorized`	Missing, malformed, or revoked key
`402`	`insufficient_credits`	Credit balance too low for this operation
`429`	`rate_limit_exceeded`	Too many requests in the current window

See Errors for the full error envelope and handling patterns.