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.

Rotation pattern

1. Generate a second key.
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.

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.