gavel-auth

Gavel Auth

Multi-tenant authentication for tests.

When to Use

• Tests get 401 Unauthorized across tenants
• Need tenant-scoped tokens or session cookies
• Debugging firm-scope mismatches
• Setting up multi-tenant test fixtures

Core Concepts

1. Tenant isolation: Each tenant has its own data scope. Tokens are scoped to a tenant.
2. Host-based routing: Multi-tenant apps often use subdomains (tenant1.app.com) or tenant headers.
3. Token scoping: A token from tenant A cannot access tenant B's resources.

Patterns

API Auth (Playwright)

// Fixture: login as tenant-specific user
test.extend<{ tenantAUser: APIRequestContext }>({
  tenantAUser: async ({}, use) => {
    const response = await request.post('/api/auth/login', {
      data: { email: UserFactory.create('tenantA').email, password: env.PASSWORD },
      headers: { 'X-Tenant': 'tenant-a' },
    });
    await use(response);
  },
});

UI Auth (Playwright)

// Navigate via tenant-specific subdomain
await page.goto(`http://tenant-a.localhost:${port}/login`);

Common Issues

Issue	Cause	Fix
401 on cross-tenant request	Token scoped to wrong tenant	Use correct tenant's credentials
404 instead of 403	App returns 404 for scope mismatch	Expected behavior for security
Session expired	Token TTL exceeded	Re-login in beforeEach