Authentication

Cadenza uses OAuth 2.0 Bearer token authentication powered by Supabase Auth.

Overview

┌─────────┐     1. Login      ┌─────────────┐
│  Client │ ───────────────── │   Cadenza   │
│         │ ◄──────────────── │   Auth      │
└─────────┘   2. Access Token └─────────────┘
     │
     │ 3. API Request + Bearer Token
     ▼
┌─────────────┐
│   Cadenza   │
│   API       │
└─────────────┘

Authentication Flow

1. Login

Authenticate with email and password to receive tokens:

TypeScript

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

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

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

const accessToken = data.session.access_token
const refreshToken = data.session.refresh_token

Python

from cadenza_client import CadenzaApi

api = CadenzaApi(BASE_URL)
session = api.auth.login(email="user@example.com", password="your-password")

access_token = session.access_token
refresh_token = session.refresh_token

Go

client := cadenza.NewClient(BaseURL)

session, err := client.Auth.Login(context.Background(), &cadenza.LoginRequest{
    Email:    "user@example.com",
    Password: "your-password",
})

accessToken := session.AccessToken
refreshToken := session.RefreshToken

2. Use Access Token

Include the access token in the Authorization header for all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Refresh Token

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

TypeScript

const { data, error } = await supabase.auth.refreshSession()
const newAccessToken = data.session?.access_token

Python

session = api.auth.refresh_token()
new_access_token = session.access_token

Go

session, err := client.Auth.RefreshToken(context.Background())
newAccessToken := session.AccessToken

Token Properties

Property	Description
accessToken	JWT token for API authentication (expires in 1 hour)
refreshToken	Token for obtaining new access tokens (longer lived)
expiresIn	Token lifetime in seconds
expiresAt	Token expiration Unix timestamp

WebSocket Authentication

For WebSocket connections, pass the access token when creating the client:

TypeScript

import { Centrifuge } from 'cadenza-client-typescript'

const client = new Centrifuge(CADENZA_WS_URL, {
  token: accessToken,
})

client.connect()

Python

from cadenza_client import Client

client = Client(WS_URL, token=access_token)
await client.connect()

Go

wsClient := cadenza.NewWSClient(WsURL, accessToken)
err := wsClient.Connect(context.Background())

Token Expiry Handling

When a token expires:

• HTTP API returns 401 Unauthorized
• WebSocket disconnects with code 3500

Handle expiry by refreshing the token and retrying the request.

Security Best Practices

1. Never expose tokens in client-side code or logs
2. Store tokens securely (e.g., httpOnly cookies, secure storage)
3. Refresh proactively before expiration to avoid interruptions
4. Use HTTPS for all API communications