Authentication

ProBeya uses Better Auth for authentication. The API supports two authentication methods: session cookies (for browser clients) and API tokens (for programmatic access).

Session-Based Authentication

Browser clients authenticate via session cookies:

Login Flow

// Using the API client
const session = await client.auth.signIn({
  email: "[email protected]",
  password: "securepassword",
});

# Using curl
curl -X POST "https://acme.probeya.com/api/trpc/auth.signIn" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securepassword"}'

On success, the server sets a secure HttpOnly session cookie. Subsequent requests include this cookie automatically.

Session Management

// Get current session
const session = await client.auth.getSession();

// Sign out
await client.auth.signOut();

// List active sessions
const sessions = await client.auth.listSessions();

// Revoke a specific session
await client.auth.revokeSession({ sessionId: "sess_abc123" });

API Token Authentication

For programmatic access (scripts, integrations, CI/CD), use API tokens:

Creating a Token

1. Navigate to Settings > API Tokens.
2. Click + Create Token.
3. Enter a name and select scopes.
4. Copy the generated token.

Using a Token

Include the token in the Authorization header:

curl -H "Authorization: Bearer probeya_tok_abc123xyz" \
  "https://acme.probeya.com/api/trpc/workspace.list"

Token Scopes

Scope	Description
read:workspace	Read workspace data
write:workspace	Create and modify workspaces
read:project	Read project data
write:project	Create and modify projects
read:board	Read boards and items
write:board	Create and modify boards and items
read:member	Read member information
write:member	Invite and manage members
admin	Full administrative access

Token Expiration

Tokens do not expire by default but can be configured with an expiration date. Expired tokens return a 401 UNAUTHORIZED error.

OAuth Providers

ProBeya supports OAuth login with:

• Google — GET /auth/google
• GitHub — GET /auth/github

Configuring OAuth (Self-Hosted)

Set the following environment variables:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

See Environment Variables for the complete list.

Two-Factor Authentication

When 2FA is enabled, the login flow requires an additional step:

// Step 1: Sign in with credentials
const result = await client.auth.signIn({
  email: "[email protected]",
  password: "securepassword",
});

// If 2FA is required, result includes a challengeId
if (result.requiresTwoFactor) {
  // Step 2: Verify the TOTP code
  await client.auth.verifyTwoFactor({
    challengeId: result.challengeId,
    code: "123456",
  });
}

Security Headers

All API responses include the following security headers:

• Strict-Transport-Security: max-age=31536000; includeSubDomains
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Content-Security-Policy: default-src 'self'