Authentication

Send a key on every authenticated request using either header:

Authorization: Bearer cvio_live_...

or

X-API-Key: cvio_test_...

Missing, malformed, revoked, expired, and unknown keys all return the same 401 unauthorized response, so a response never reveals whether a key exists. GET /operations and GET /openapi.json do not require a key.

Key modes

• cvio_live_... keys create real jobs that spend your organization's credits.
• cvio_test_... keys run the same endpoints with simulated results and never hold or charge credits. See Test mode.

Test and live keys are isolated from each other: a test key cannot see, cancel or delete jobs made with a live key of the same organization, and the other way round. Within one mode, every key of your organization sees the same jobs, so a rotated or replacement key keeps its history.

Scopes

Each key carries a set of scopes, chosen when you create it. Grant only what an integration needs.

A valid key without the required scope returns 403 forbidden_scope, and error.details.required_scope names the missing scope. GET /me works for any valid key and shows the key's mode and scopes:

{
	"organization_id": "7c1c0a52-7b0a-4b34-9a52-0c8d5d3f1b11",
	"mode": "test",
	"scopes": ["job.read", "job.write"],
	"credits": { "balance": 18 }
}

Keys created before scopes existed have all four.

Manage keys

Create, rotate and revoke keys in your organization's Settings → API Keys tab.

• The full secret is shown once, when the key is created or rotated. It cannot be retrieved later; the dashboard only shows a short prefix.
• Rotate issues a new secret for the same key and the old secret stops working immediately. For a rollover with no downtime, create a second key, switch your integration over, then revoke the old one.
• Revoke rejects every later request made with the key.

Protect your keys

Never put an API key in browser code, a mobile app, a public repository or a log. Keep it in server-side secrets. Requests from a browser are only allowed from https://convertere.io (used by the interactive reference), so your own web pages cannot call the API directly; call it from your server.