Authentication
API keys, modes, Organizations, and how each request finds the provider credential it runs with.
Every data-plane request carries one API key as a bearer token:
Authorization: Bearer koil_live_...Create and revoke keys in the Koil admin console. A key belongs to one Organization and one mode, and both follow from the key alone: there is no Organization or mode parameter to send.
Modes
A key is either live (koil_live_…) or test (koil_test_…). The prefix makes the mode visible wherever the key appears, but it is checked against the key's own mode rather than trusted: a mismatched prefix, an unprefixed value, or a key that carries both or neither mode is refused with unauthorized. See Test mode for what a test key can do.
If Koil cannot validate a key at all (its identity provider is unavailable), the request answers 503 with service_unavailable and a Retry-After header. Nothing was attempted and your key was not judged, so retry the same request after that many seconds.
Organizations
Everything Koil stores — Auth Integrations, Connections, Connected Profiles, publish requests, media, Event Destinations — belongs to the key's Organization and mode. A request can never read or act on another Organization's resources, and live and test resources never mix.
Connected Profiles, not credentials
Provider operations never take a provider token. They take a connectedProfileId, and Koil resolves everything else:
- The Connected Profile, scoped to your Organization.
- The Connection it was created from, and that Connection's current provider credential.
- Whether that credential can run this operation: its kind, its scopes, the provider profile it reaches, and its health.
If any check fails — the grant expired, lacks a scope, or no longer reaches the profile — the request fails before any provider call, with invalid_token or scope_insufficient. A scope Koil cannot confirm the grant holds counts as missing. A Connected Profile of another provider than the operation's (an Instagram profile on a Facebook route, say) is refused with validation_error, even when both were authorized through the same Facebook Login.
Two end users who authorize the same provider account produce two Connected Profiles. Choose the one whose user (or automation) is taking the action, so the provider's own audit trail names the right actor. Koil never picks a credential for you.
Keyless routes
Provider discovery (GET /v1/providers, GET /v1/providers/{providerId}, GET /v1/providers/{providerId}/surfaces) needs no key: it describes what Koil supports, not anything of yours.