Authentication

All SuperWaba API endpoints require authentication. This page explains how to obtain credentials and authenticate your requests to the WhatsApp Business API.

---

Required headers

Every API request must include these headers:

x-org-id: your-organization-id
Authorization: Bearer <session-token>
Content-Type: application/json

Header	Description
x-org-id	Your organization UUID — identifies which WhatsApp Business account to use
Authorization	Bearer token from authentication
Content-Type	Always application/json for request bodies

---

Getting your organization ID

You can find your organization ID in two ways:

1. Settings page — Navigate to Settings > General in the SuperWaba dashboard
2. URL — Copy it from your browser URL when logged in: https://app.superwaba.com/org/{org-id}/...

Example organization ID:

x-org-id: a1b2c3d4-5678-90ab-cdef-1234567890ab

---

Session tokens

Session tokens are issued when a user signs in through the SuperWaba web application or mobile app.

How tokens work

1. User signs in via email/password or OAuth (Google, etc.)
2. Supabase Auth issues a JWT session token
3. Include this token in your Authorization header

Getting a token (for development/testing)

Use the Supabase Auth API to obtain a session token:

Request:

POST https://your-project.supabase.co/auth/v1/token?grant_type=password
Content-Type: application/json
apikey: your-supabase-anon-key

{
  "email": "developer@yourcompany.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "v1_refresh_abc123...",
  "user": {
    "id": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx",
    "email": "developer@yourcompany.com"
  }
}

Then use access_token in your API calls:

curl -X GET "https://app.superwaba.com/api/whatsapp/contacts" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-org-id: a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Content-Type: application/json"

Token refresh

Tokens expire after 1 hour. Use the refresh token to obtain a new access token:

POST https://your-project.supabase.co/auth/v1/token?grant_type=refresh_token
Content-Type: application/json
apikey: your-supabase-anon-key

{
  "refresh_token": "v1_refresh_abc123..."
}

---

Server-to-server integrations

For backend services that need to interact with SuperWaba without user sessions, use one of these approaches:

Option 1: Service role key (recommended for webhooks)

Use the Supabase service role key for server-side operations. This bypasses Row Level Security.

curl -X GET "https://app.superwaba.com/api/whatsapp/contacts" \
  -H "Authorization: Bearer your-supabase-service-role-key" \
  -H "x-org-id: a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Content-Type: application/json"

caution

Never expose the service role key in client-side code. Only use it in server environments.

Option 2: Webhook system (no auth needed)

For receiving data from SuperWaba, configure webhooks instead. SuperWaba pushes events to your endpoint — no authentication required on your side.

See the Webhook Events documentation for setup.

---

Error responses

Missing auth header (401):

{
  "success": false,
  "error": "Unauthorized"
}

Expired token (401):

{
  "success": false,
  "error": "Token expired. Please refresh your session."
}

Invalid org ID (403):

{
  "success": false,
  "error": "User is not a member of this organization"
}

Missing org header (400):

{
  "success": false,
  "error": "x-org-id header is required"
}

---

Rate limits

All API endpoints are rate-limited to protect service quality:

Tier	Limit	Window
Standard	100 requests	per minute
Messaging	30 messages	per second
Bulk operations	10 requests	per minute

When rate limited, you'll receive:

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

---

Security best practices

• Rotate tokens regularly — don't store long-lived tokens in code
• Use environment variables — never hardcode credentials
• Restrict by IP — if possible, allowlist server IPs in your firewall
• Use HTTPS only — all API traffic must use TLS
• Audit access — review API usage in Settings > Developer > Logs