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 by a super_admin in the admin panel under Configuration -> API Access.
• 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.
• lastUsedAt is updated asynchronously after successful authentication.

Company-scoped keys

API keys are scoped to exactly one company. The company is assigned when the key is created in the admin panel. All API requests made with a key automatically operate within the context of that company — there is no need to pass a companyId parameter on requests.

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.

Keys created before company scoping was introduced have no companyId and continue to work for non-workflow endpoints (GET /api/v1/companies, GET /api/v1/jobs/{sessionId}, POST /api/v1/webhooks/test). Workflow endpoints require a company-scoped key and return 403 if the key lacks a company assignment.

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.