API Key Authentication Guide¶

Every ConnectGain API request is authenticated with an organization API key: a cg_-prefixed secret created in Settings → API Keys and sent in the X-API-Key header.

curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*John*' \
 --header 'X-API-Key: cg_your_api_key_here'

A key is scoped to the organization that created it: whatever you call, you only ever see that organization's data.

Who can create a key¶

Only the organization's Owner or an Admin can create API keys. Agents and Project Managers see an error ("Only organization owners and admins can create API keys") and should ask an Owner or Admin to create one.

A key is always created for the organization you are currently signed into. When you create it you choose what it may do — send messages and/or read messages — and, optionally, how many days it stays valid (1 to 3,650). The full key is shown once; copy it then, because it cannot be shown again.

Treat a key like a password: anyone holding it can act for your organization through the API. Never put it in a mobile app, a website's code, a shared document or a Postman collection's description. If a key may have been exposed, delete it in Settings → API Keys and create a new one.

Where the key works¶

REST API proxy (your records)¶

Base URL: https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/<resource>

Resources: contacts, companies, deals, conversations, messages, tasks, projects, templates, channel_accounts.

Supported Query Parameters:

select - Specify columns to return: ?select=id,first_name,last_name
order - Order results: ?order=created_at.desc
Filter operators:
?first_name=eq.John - Equals
?first_name=ilike.*John* - Case-insensitive like (use * for wildcards)
?age=gt.18 - Greater than
?age=gte.18 - Greater than or equal
?age=lt.65 - Less than
?age=lte.65 - Less than or equal
?tags=cs.{tag1,tag2} - Array contains
?id=in.(uuid1,uuid2) - In list
limit - Limit results: ?limit=50
offset - Pagination: ?offset=100

Example Queries:

# Search contacts by name
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*John*' \
 --header 'X-API-Key: cg_...'

# Get conversations with pagination
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?limit=20&offset=0&order=last_message_at.desc' \
 --header 'X-API-Key: cg_...'

# Get specific columns only
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?select=id,first_name,last_name,phones' \
 --header 'X-API-Key: cg_...'

Endpoints (operations)¶

Purpose-built operations — sending messages, creating leads, searching, bulk import, bot control — take the same header:

# Example: Insert message
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/insert-message' \
 --header 'X-API-Key: cg_your_api_key_here' \
 --header 'Content-Type: application/json' \
 --data '{
 "phone": "+15550100001",
 "content": "Hello from API",
 "direction": "outgoing"
 }'

The full list is in the Complete API reference.

Key Differences¶

Surface	Header Name	Use Case
REST API proxy	`X-API-Key`	Read and write your organization's records
Endpoints	`X-API-Key`	Operations: send, search, import, bot control
Mobile API	`X-API-Key` or a user token from login	Agent-attributed actions — see Mobile API

Security Notes¶

API keys are scoped to your organization. A key can never read or change another organization's data.
A key is organization-wide, not per-resource. The Send messages and Read messages switches in Settings → API Keys describe the messaging endpoints; they do not narrow the REST API proxy, so any valid key can read and write every resource listed above for its own organization. Issue one key per integration and revoke it when the integration ends, rather than relying on the switches to fence a key off from your contacts or deals.
Treat the key like a password. Keep it in a secrets manager or server-side configuration — never in client-side code, a mobile app bundle or a public repository.
One key per integration, with an expiry. Then a single integration can be revoked without touching the others.
Always use HTTPS.

Troubleshooting¶

Error: "No API key found in request"¶

Cause: The X-API-Key header is missing or misspelt
Fix: Send the key in the X-API-Key header exactly as shown above

Error: "Invalid or expired API key"¶

Cause: API key is invalid, expired, or inactive
Fix: Generate a new API key from Settings → API Keys

Error: "Table not allowed via REST API proxy" (403)¶

Cause: The resource in the URL is not one the proxy exposes
Fix: Use one of the resources listed above; everything else is managed in the app

Error: "Invalid URL format"¶

Cause: Incorrect proxy URL format
Fix: Use format: /rest-api-proxy/<resource>?<query_params>

Generating API Keys¶

Log into ConnectGain
Go to Settings → API Keys
Click "Generate API Key"
Save the key immediately (it's only shown once)