Authentication

Overview

Nexus uses Supabase Auth for identity management. All API requests (except public webhook endpoints) require a valid JWT bearer token.

Obtaining a token

Email/password login

curl -X POST https://<project-ref>.supabase.co/auth/v1/token?grant_type=password \
  -H "apikey: <anon-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "password": "••••••••"
  }'

Response (abbreviated):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MjAyNS0w..."
}

Token refresh

curl -X POST https://<project-ref>.supabase.co/auth/v1/token?grant_type=refresh_token \
  -H "apikey: <anon-key>" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "v1.MjAyNS0w..."}'

Using the token

Include the JWT in the Authorization header of every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

For Supabase PostgREST endpoints, also include the apikey header:

apikey: <anon-key>

Token claims

The JWT contains these relevant claims:

Claim	Description
sub	User ID (UUID)
email	User email
role	Supabase role (authenticated)
app_metadata.organization_id	Current organization ID
app_metadata.org_role	Organization role (owner, admin, member)

Row-Level Security

The JWT's organization_id claim is used by PostgreSQL RLS policies to filter data. A user can only access rows belonging to their organization. This is enforced at the database level — the API cannot bypass it.

Webhook authentication

Inbound webhook endpoints (e.g., whatsapp-webhook, shopify-webhook) use different authentication mechanisms:

• Verify token — a shared secret validated on webhook registration (WhatsApp, Meta).
• HMAC signature — request body signed with a shared secret (Shopify).
• Bearer token — a static token in the Authorization header (internal webhooks).

Webhook authentication details are not included in the public OpenAPI spec for security reasons.

Best practices

1. Never hardcode tokens in client-side code. Use Supabase Auth SDK for token management.
2. Refresh tokens before they expire (expires_in is in seconds).
3. Never use the service role key in client applications.
4. Store tokens securely (httpOnly cookies or secure storage, not localStorage in production).