Authentication

Every /api/v1 request authenticates with an API key. There is no session, cookie, or OAuth flow on this surface.

API keys

The API expects:

Authorization: Bearer aok_<64 lowercase hex chars>

Characteristics

• Keys are generated in the admin panel under Configuration -> API Access by platform super_admins or organization org_admins.
• The plaintext key is shown once at creation time and is never stored server-side.
• Steve stores only SHA-256(plaintextKey) in the apiKeys table.
• Revoked keys return 403 Forbidden.
• Unknown or malformed keys return 401 Unauthorized.
• Successful authentication updates lastUsedAt synchronously, throttled to at most once every 60 seconds.

Company-scoped keys

API keys are usually scoped to one company. Organization org_admins must assign a company when creating a key. Platform super_admins can create either company-scoped or unscoped keys. Requests made with a company-scoped key automatically operate within that company's context — there is no need to pass a companyId parameter.

This scoping determines:

• Which workflows the key can discover and create sessions for (only workflows explicitly assigned to the company).
• Which sessions the key can submit and poll (only sessions created by the same key).
• Which webhook deliveries the key receives.

Legacy keys and keys created without a company by a platform super_admin have no companyId. Unscoped keys receive 403 Forbidden on company-scoped endpoints, including GET /api/v1/jobs/{sessionId}.

Rotation pattern

1. Generate a second key scoped to the same company.
2. Roll your integration to the new key.
3. Confirm traffic has moved.
4. Revoke the old key.

Because the plaintext key is only shown once, rotation is the recovery path for a lost key as well as for a suspected leak.

Security guidance

• Treat API keys as server-side secrets. Do not embed them in browser bundles or mobile apps — /api/v1 allows all origins, but that does not make a key sent from a browser private.
• Rotate keys proactively rather than waiting for incident response.
• For webhook consumers, verify X-Webhook-Signature before acting on payloads. See Webhooks.