Authentication

Billbora uses a hybrid authentication system designed for both server-to-server integrations and frontend applications. This guide covers all authentication methods and best practices.

Authentication Methods

API Keys

Simple authentication for server-to-server integrations

JWT Tokens

Secure authentication for frontend applications with organization context

API Keys

API keys are the simplest way to authenticate with the Billbora API, ideal for server-to-server integrations.

Getting API Keys

Log into Billbora

Navigate to app.billbora.com and log in.

Go to API Settings

Navigate to Settings → API → Credentials.

Generate API Key

Click Generate New API Key and copy the generated key.

Store this key securely - it won’t be shown again!

Using API Keys

Include your API key in the Authorization header with the Bearer scheme:

curl -X GET \
  https://api.billbora.com/api/v1/invoices/ \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.billbora.com/api/v1/invoices/', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})

import requests

response = requests.get(
    'https://api.billbora.com/api/v1/invoices/',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

API Key Security

Best Practices

Store API keys in environment variables, never in code
Use different keys for different environments (development, staging, production)
Rotate keys regularly (every 90 days recommended)
Monitor API key usage in your dashboard
Revoke compromised keys immediately

Key Management

Each organization can have multiple API keys
Keys can be scoped to specific permissions
Usage analytics are available per key
Keys can be temporarily disabled without deletion

JWT Authentication

JWT authentication is designed for frontend applications and provides organization context switching capabilities.

Authentication Flow

The JWT authentication flow involves multiple steps:

Step 1: Supabase Authentication

First, authenticate with Supabase to get the initial JWT token:

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

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-supabase-anon-key'
)

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

const supabaseToken = data.session?.access_token

import { createClient, SupabaseClient } from '@supabase/supabase-js'

const supabase: SupabaseClient = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

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

if (error) {
  throw new Error(`Authentication failed: ${error.message}`)
}

const supabaseToken = data.session?.access_token

Step 2: Token Exchange

Exchange the Supabase token for a Billbora token with organization context:

const response = await fetch('https://api.billbora.com/api/v1/users/auth/exchange/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    supabase_token: supabaseToken,
    organization_id: 'org_1234567890' // Optional
  })
})

const tokens = await response.json()
// tokens.access, tokens.refresh, tokens.organization

interface TokenExchangeRequest {
  supabase_token: string
  organization_id?: string
}

interface TokenExchangeResponse {
  access: string
  refresh: string
  access_expires: number
  organization: {
    id: string
    name: string
    role: 'owner' | 'admin' | 'member'
  }
}

const exchangeTokens = async (
  supabaseToken: string, 
  organizationId?: string
): Promise<TokenExchangeResponse> => {
  const response = await fetch('https://api.billbora.com/api/v1/users/auth/exchange/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      supabase_token: supabaseToken,
      organization_id: organizationId
    })
  })

  if (!response.ok) {
    const error = await response.json()
    throw new Error(`Token exchange failed: ${error.error}`)
  }

  return response.json()
}

Step 3: Using JWT Tokens

Use the Billbora JWT token for API requests:

const response = await fetch('https://api.billbora.com/api/v1/invoices/', {
  headers: {
    'Authorization': `Bearer ${tokens.access}`,
    'Content-Type': 'application/json'
  }
})

class BillboraAPIClient {
  private accessToken: string
  private refreshToken: string
  
  async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
    const response = await fetch(`https://api.billbora.com/api/v1${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    })
    
    if (response.status === 401) {
      await this.refreshTokens()
      // Retry the request with new token
      return this.request<T>(endpoint, options)
    }
    
    return response.json()
  }
}

Token Refresh

JWT tokens expire after 1 hour. Use the refresh token to get a new access token:

const refreshResponse = await fetch('https://api.billbora.com/api/v1/users/auth/refresh/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refresh: refreshToken
  })
})

const newTokens = await refreshResponse.json()
// Update stored tokens

const refreshTokens = async (refreshToken: string): Promise<TokenExchangeResponse> => {
  const response = await fetch('https://api.billbora.com/api/v1/users/auth/refresh/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      refresh: refreshToken
    })
  })

  if (!response.ok) {
    throw new Error('Token refresh failed - please log in again')
  }

  const data = await response.json()
  return {
    access: data.access,
    refresh: refreshToken, // Refresh token doesn't change
    access_expires: data.access_expires || 3600,
    organization: getCurrentOrganization() // Keep current org context
  }
}

Organization Context

One of the key features of Billbora’s authentication system is organization context switching.

Switching Organizations

Users can belong to multiple organizations and switch between them:

const switchOrganization = async (organizationId) => {
  // Get fresh Supabase token
  const { data } = await supabase.auth.getSession()
  const supabaseToken = data.session?.access_token
  
  // Exchange for new organization context
  const newTokens = await exchangeTokens(supabaseToken, organizationId)
  
  // Update stored tokens
  localStorage.setItem('billbora_auth', JSON.stringify(newTokens))
  
  return newTokens
}

const switchOrganization = async (organizationId: string): Promise<TokenExchangeResponse> => {
  const { data } = await supabase.auth.getSession()
  
  if (!data.session?.access_token) {
    throw new Error('Supabase session expired')
  }
  
  const newTokens = await exchangeTokens(data.session.access_token, organizationId)
  
  // Update auth state
  setAuthTokens(newTokens)
  
  return newTokens
}

Getting Available Organizations

Fetch organizations the current user has access to:

const organizations = await fetch('https://api.billbora.com/api/v1/users/me/organizations/', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
})

const orgList = await organizations.json()

interface UserOrganization {
  id: string
  name: string
  role: 'owner' | 'admin' | 'member'
  is_active: boolean
}

const getUserOrganizations = async (accessToken: string): Promise<UserOrganization[]> => {
  const response = await fetch('https://api.billbora.com/api/v1/users/me/organizations/', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  })
  
  return response.json()
}

Error Handling

Handle authentication errors gracefully:

Common Error Codes

invalid_credentials: Wrong email/password combination
token_expired: JWT token has expired, refresh needed
invalid_token: Malformed or invalid token
organization_access_denied: User doesn’t have access to requested organization
rate_limited: Too many authentication attempts

Error Response Format

{
  "error": {
    "code": "token_expired",
    "message": "The provided token has expired",
    "details": {
      "expired_at": "2025-01-15T10:30:00Z"
    }
  }
}

Security Best Practices

Token Storage

Store tokens securely (not in localStorage for sensitive apps)
Use httpOnly cookies for web applications when possible
Clear tokens on logout
Implement token expiration checking

Network Security

Always use HTTPS in production
Implement proper CORS policies
Validate SSL certificates
Monitor for unusual authentication patterns

Application Security

Implement proper session management
Use secure password requirements
Enable two-factor authentication
Implement account lockout policies

Monitoring

Monitor authentication failures
Set up alerts for suspicious activity
Regularly audit API key usage
Implement request rate limiting

Complete Authentication Example

Here’s a complete example of implementing authentication in a React application:

import { useState, useEffect, useCallback, createContext, useContext } from 'react'
import { createClient } from '@supabase/supabase-js'

interface AuthState {
  isAuthenticated: boolean
  isLoading: boolean
  user: any
  organization: any
  error: string | null
}

const AuthContext = createContext<any>(null)

export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [state, setState] = useState<AuthState>({
    isAuthenticated: false,
    isLoading: true,
    user: null,
    organization: null,
    error: null
  })

  const supabase = createClient(
    process.env.REACT_APP_SUPABASE_URL!,
    process.env.REACT_APP_SUPABASE_ANON_KEY!
  )

  const login = useCallback(async (email: string, password: string) => {
    setState(prev => ({ ...prev, isLoading: true, error: null }))
    
    try {
      // Step 1: Supabase authentication
      const { data, error } = await supabase.auth.signInWithPassword({ email, password })
      if (error) throw error

      // Step 2: Token exchange
      const tokens = await exchangeTokens(data.session!.access_token)
      
      // Step 3: Get user info
      const user = await fetchUser(tokens.access)
      
      setState({
        isAuthenticated: true,
        isLoading: false,
        user,
        organization: tokens.organization,
        error: null
      })
      
      // Store tokens
      localStorage.setItem('billbora_auth', JSON.stringify(tokens))
      
    } catch (error: any) {
      setState(prev => ({
        ...prev,
        isLoading: false,
        error: error.message
      }))
    }
  }, [])

  const logout = useCallback(async () => {
    await supabase.auth.signOut()
    localStorage.removeItem('billbora_auth')
    
    setState({
      isAuthenticated: false,
      isLoading: false,
      user: null,
      organization: null,
      error: null
    })
  }, [])

  return (
    <AuthContext.Provider value={{ ...state, login, logout }}>
      {children}
    </AuthContext.Provider>
  )
}

export const useAuth = () => {
  const context = useContext(AuthContext)
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider')
  }
  return context
}

Next Steps

Frontend Integration

Learn how to integrate authentication in your frontend application

API Reference

Complete authentication API reference

Organization Management

Learn about multi-tenant organization features

Security Guide

Advanced security practices and configurations

​Authentication

​Authentication Methods

API Keys

JWT Tokens

​API Keys

​Getting API Keys

​Using API Keys

​API Key Security

​JWT Authentication

​Authentication Flow

​Step 1: Supabase Authentication

​Step 2: Token Exchange

​Step 3: Using JWT Tokens

​Token Refresh

​Organization Context

​Switching Organizations

​Getting Available Organizations

​Error Handling

​Security Best Practices

Token Storage

Network Security

Application Security

Monitoring

​Complete Authentication Example

​Next Steps

Frontend Integration

API Reference

Organization Management

Security Guide

Authentication

Authentication Methods

API Keys

Getting API Keys

Using API Keys

API Key Security

JWT Authentication

Authentication Flow

Step 1: Supabase Authentication

Step 2: Token Exchange

Step 3: Using JWT Tokens

Token Refresh

Organization Context

Switching Organizations

Getting Available Organizations

Error Handling

Security Best Practices

Complete Authentication Example

Next Steps