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 shortly after the request (deferred, at most once every 60 seconds per key).

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. Let sessions created with the old key finish (a session lives 30 minutes), then revoke the old key.

A workflow session stays bound to the key that created it:

• only that key can submit it or poll its job; the new key gets 404 on submit and 403 on GET /api/v1/jobs/{sessionId}
• its webhooks are signed with the old key's secret, so keep verifying with both secrets until the old key's sessions are done
• clientSubmissionId is held per key, so a retry sent with the new key creates a new session instead of returning the old key's one

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.