Runbook

Session Issues

Users logged out unexpectedly

Symptoms: Users are redirected to login despite valid credentials.

Diagnosis:

1. Check browser dev tools → Application → Cookies
2. Verify cookie domain matches the current domain
3. Check session TTL in database

Common Causes:

• Cookie domain misconfiguration (check BETTER_AUTH_URL)
• Session expired in database
• NODE_ENV mismatch between server and cookie settings

Resolution:

# Check session in database
psql -c "SELECT * FROM session WHERE user_id = '<user_id>'"

Session cookie not set

Symptoms: API calls succeed but no session cookie in response.

Diagnosis:

1. Check response headers for set-cookie
2. Verify sameSite and secure settings
3. Check CORS configuration

Resolution:

• Ensure CORS_ORIGIN includes the requesting domain
• Check trustedOrigins in auth config

API Key Issues

API key requests fail with 401 Unauthorized

Symptoms: Requests with x-api-key header return 401.

Diagnosis:

const data = await auth.api.verifyApiKey({ body: { key: apiKey } });
console.log(data.valid, data.key);

Common Causes:

• API key invalid or revoked
• API key not associated with a user (referenceId missing)
• Organization mismatch

Resolution:

1. Verify API key exists in database
2. Ensure key has referenceId set
3. Check x-tenant-id header if org-specific key

Organization Issues

"User does not have access to organization"

Symptoms: 401 error when accessing org-scoped data.

Diagnosis:

const membership = await basePrisma.member.findFirst({
  where: { userId: user.id, organization: { slug: orgSlug } },
});

Resolution:

• User must be a member of the organization
• Check membership table for user-org pair

"User has no organization"

Symptoms: 401 error on first login, no org context.

Resolution:

• Ensure user is added to an organization during signup
• Check organization hook or seed data

Extension Token Issues

Extension token invalid/expired

Symptoms: Extensions fail to authenticate with Action API.

Diagnosis:

• Check token expiration
• Verify EXTENSION_TOKEN_SECRET matches

Resolution:

// Re-generate token for testing
const token = generateExtensionToken({
  orgId: "...",
  userId: "...",
  scopes: ["read", "write"],
});

Common Causes:

• Token TTL expired
• EXTENSION_TOKEN_SECRET mismatch between servers
• Token not scoped correctly

Debugging Tips

Enable Auth Logging

// In auth config
advanced: {
  verbose: true, // Enable verbose logging
}

Check Session in Handler

app.get("/debug/session", requireAuth, async (c) => {
  return c.json({
    user: c.get("user"),
    session: c.get("session"),
    org: c.get("org"),
  });
});

Database Queries

-- Check active sessions
SELECT s.id, s.expires_at, u.email 
FROM session s 
JOIN "user" u ON s.user_id = u.id;

-- Check API keys
SELECT k.id, k.reference_id, k.name 
FROM api_key k 
WHERE k.revoked = false;