Authentication

# Authenticate with an API key — works immediately
curl https://acme.probeya.com/api/v1/workspaces \
  -H "Authorization: Bearer probeya_sk_live_a1b2c3d4..."

ProBeya supports three authentication methods depending on your integration type.

​

Choose your auth method

​

API keys

API keys are the recommended way to authenticate programmatic access. Each key is scoped to a single organization and inherits the permissions of the user who created it.

​

Generate a key

​

Use the key

curl https://acme.probeya.com/api/v1/actions?boardId=clx_board_1 \
  -H "Authorization: Bearer probeya_sk_live_a1b2c3d4e5f6..."

​

Key format and security

probeya_sk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
|_____________| |______| |____________________________________________|
    prefix      lookup              bcrypt-hashed secret
                prefix
               (8 chars)            (40 hex chars = 160 bits entropy)

• Only the bcrypt hash is stored in the database — the full key cannot be recovered
• The 8-character lookup prefix enables efficient database queries without scanning all keys
• bcrypt.compare() is timing-safe, preventing timing attacks
• Revoked or expired keys are rejected after hash verification (no information leakage about key existence)

​

Scopes

API keys can be restricted to specific scopes:

​

Error responses

// 401 — Missing or invalid key
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

// 403 — Key is valid but lacks required scope
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have scope: write:actions"
  }
}

// 403 — Key is revoked
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key has been revoked"
  }
}

​

Session authentication (browser)

The ProBeya web app uses Auth.js v5 with JWT-based sessions stored in HTTP-only cookies.

​

Flow

1. User submits email + password (or clicks SSO button)
        |
2. Auth.js validates credentials (bcrypt.compare for passwords, OIDC for SSO)
        |
3. JWT issued with userId + defaultOrganizationId
        |
4. Token stored in HTTP-only cookie (authjs.session-token)
        |
5. Middleware reads JWT on every request
        |
6. tRPC context receives authenticated user
        |
7. orgProcedure wraps query in RLS-scoped transaction

​

Session parameters

​

SSO providers

ProBeya supports enterprise SSO via OpenID Connect. Providers are conditionally loaded based on environment variables — missing vars do not crash the server.

Redirect URI pattern: {APP_URL}/api/auth/callback/{provider-id}

​

MCP authentication

MCP connections use the same API key system with an additional MCP-specific key type for granular AI controls:

See the MCP guide for details.

​

Password security

Passwords are hashed with bcrypt (10 salt rounds). Login attempts (both successful and failed) are recorded in the login_history table for compliance auditing.

​

Rate limiting

​

Next steps