Authentication

Authentication and authorization guide for Lager Guru API.

Overview

Lager Guru uses Supabase Auth for authentication, supporting multiple authentication methods including email/password, OAuth, and SSO.

Authentication Methods

Email/Password

Standard email and password authentication.

Sign Up

curl -X POST https://api.lager-guru.hashmatrix.de/auth/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password",
    "data": {
      "tenant_id": "tenant-uuid"
    }
  }'

Sign In

curl -X POST https://api.lager-guru.hashmatrix.de/auth/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password"
  }'

TypeScript Example

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

// Sign up
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password',
  options: {
    data: {
      tenant_id: 'tenant-uuid'
    }
  }
});

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password'
});

OAuth Providers

Support for OAuth providers (Google, GitHub, etc.).

OAuth Sign In

// Google OAuth
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://your-app.com/callback'
  }
});

// GitHub OAuth
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github',
  options: {
    redirectTo: 'https://your-app.com/callback'
  }
});

SSO (Enterprise)

Enterprise SSO support via OIDC and SAML.

See SSO Setup for detailed SSO configuration.

API Authentication

Access Tokens

All API requests require an access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Getting an Access Token

const { data: { session } } = await supabase.auth.getSession();
const accessToken = session?.access_token;

Making Authenticated Requests

curl -X GET https://api.lager-guru.hashmatrix.de/v1/orders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.lager-guru.hashmatrix.de/v1/orders', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

Token Management

Token Refresh

Access tokens expire after a set period. Refresh tokens automatically:

const { data: { session }, error } = await supabase.auth.refreshSession();

Token Expiration

• Access Token: Typically expires in 1 hour
• Refresh Token: Typically expires in 30 days
• Auto Refresh: Supabase client handles automatic refresh

Multi-Tenant Authentication

Tenant Context

When authenticating, include tenant context:

const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'password',
  options: {
    data: {
      tenant_id: 'tenant-uuid'
    }
  }
});

Tenant Switching

Switch tenant context for authenticated users:

// Update user metadata with new tenant
const { data, error } = await supabase.auth.updateUser({
  data: {
    tenant_id: 'new-tenant-uuid'
  }
});

Row-Level Security (RLS)

Authentication tokens include user claims used for RLS:

• User ID: Authenticated user identifier
• Tenant ID: User's tenant context
• Role: User role and permissions

RLS policies automatically filter data based on these claims.

See RLS Policies for detailed information.

Service Role

For server-side operations, use the service role key (bypasses RLS):

const supabaseAdmin = createClient(
  SUPABASE_URL,
  SUPABASE_SERVICE_ROLE_KEY
);

Service Role Key

Never expose the service role key in client-side code. Use only in secure server environments.

Best Practices

Security

1. Never Expose Keys: Keep API keys and service role keys secure
2. Use HTTPS: Always use HTTPS for authentication requests
3. Token Storage: Store tokens securely (httpOnly cookies recommended)
4. Token Rotation: Implement token rotation for long-lived sessions
5. Validate Tokens: Always validate tokens on the server side

Error Handling

try {
  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password
  });
  
  if (error) {
    // Handle authentication error
    switch (error.message) {
      case 'Invalid login credentials':
        // Invalid credentials
        break;
      case 'Email not confirmed':
        // Email verification required
        break;
      default:
        // Other errors
    }
  }
} catch (error) {
  // Handle network or other errors
}

Session Management

// Check current session
const { data: { session } } = await supabase.auth.getSession();

if (session) {
  // User is authenticated
  const userId = session.user.id;
  const accessToken = session.access_token;
} else {
  // User is not authenticated
  // Redirect to login
}

// Listen for auth state changes
supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'SIGNED_IN') {
    // User signed in
  } else if (event === 'SIGNED_OUT') {
    // User signed out
  }
});

Troubleshooting

Common Issues

Invalid credentials

• Verify email and password
• Check for typos
• Ensure account exists

Token expired

• Refresh the session
• Re-authenticate if refresh fails
• Check token expiration settings

Permission denied

• Verify user role and permissions
• Check RLS policies
• Ensure tenant context is correct

Related Documentation

• API Reference - Complete API documentation
• SSO Setup - Enterprise SSO configuration
• RLS Policies - Row-Level Security
• Multi-Tenant Auth - Multi-tenant authentication

Next Steps

• API Reference - Explore API endpoints
• SSO Setup - Configure enterprise SSO
• Rate Limits - API rate limits