Authentication

Steve uses three distinct authentication models.

1. API keys for external integrations

The external integration 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.

2. Invitation tokens for onboarding

The invitation flow is capability-based rather than session-based:

• GET /api/invitation/validate?token=...
• POST /api/invitation/complete

Characteristics

• Tokens are single-use.
• Tokens expire after 72 hours.
• complete requires a password with a minimum length of 8 characters.
• Invalid, expired, and consumed invitations are reported deterministically.

This surface is designed for browser onboarding, so it does not use API keys or Convex session tokens.

3. Convex session bearer tokens for the workflow agent

The private workflow agent endpoint expects a Convex Auth session token:

Authorization: Bearer <convex-session-token>

Characteristics

• The caller must already be authenticated through Convex Auth.
• The caller must be an admin user with the super_admin role.
• Non-admin or non-super-admin callers receive 403.
• Unauthenticated callers receive 401.
• Browser callers must also originate from an allowed ALLOWED_ORIGINS entry.

Security guidance

• Treat API keys as server-side secrets; do not embed them in browser bundles or mobile apps.
• Rotate API keys proactively rather than waiting for incident response.
• Keep invitation tokens out of logs and analytics payloads.
• For webhook consumers, verify X-Webhook-Signature before acting on payloads.
• Use the Workflow Agent API page for maintainer details instead of treating it as a public integration surface.