ConnectGain API Authentication Guide¶

This guide covers the authentication methods the ConnectGain API supports and how to set each one up. The examples reference the Postman collection at ../07-api/connectgain.postman_collection.json — see the Postman guide for import instructions.

On this page:

Authentication Methods
Getting a User Token — Step by Step
Collection Variables
Complete Testing Workflow
Which Method to Use

Authentication Methods¶

ConnectGain supports 2 authentication methods:

1. Organization API key (X-API-Key)¶

Best for: External systems, third-party integrations, automation — every public endpoint and the REST API proxy.

X-API-Key: cg_abc123def456...

Keys are created in Settings → API Keys by an owner or admin, shown once, and scoped to your organization. See API key authentication.

Best for: Actions that should be attributed to a specific agent — the Mobile API (contacts, conversations, call-recording upload) and the organization endpoints (List Organizations, Check Subscription).

Authorization: Bearer USER_ACCESS_TOKEN

The token comes from the login endpoint below, identifies the signed-in user, and expires — log in again when it does.

Getting a User Token — Step by Step¶

POST {{url}}/functions/v1/mobile-api/login
Content-Type: application/json

{
 "email": "your_email@example.com",
 "password": "your_password"
}

Response:

{
 "access_token": "eyJ...",
 "refresh_token": "abc...",
 "expires_in": 2592000,
 "user": {
 "id": "user-uuid",
 "email": "your_email@example.com",
 "organization_id": "org-uuid"
 }
}

Step 2: Save the token¶

Copy access_token into the user_token collection variable — or add a small Postman test script on the login request that does it for you:

pm.collectionVariables.set("user_token", pm.response.json.access_token);

Step 3: Use it¶

Send Authorization: Bearer {{user_token}} on the endpoints that require a user.

A 401 means the token has expired or the credentials were wrong — log in again. A 403 means the account is deactivated or suspended.

Collection Variables¶

Add these variables to your collection:

// Base variables
url = https://txpaxbxhnvnhsjwwaeoy.supabase.co
api_key = cg_your_api_key_here
organization_id = 00000000-0000-4000-8000-000000000005

// Set by the login endpoint
user_token = (auto-populated by the login test script)

Complete Testing Workflow¶

Phase 1: API key¶

Search Contacts — confirms the key works and is scoped to your organization
List Contacts through the REST API proxy

Phase 2: User token¶

Login — get a token
List Organizations — verify the token works
Check Subscription

Phase 3: Full Workflow¶

Create resources (contacts, companies, deals)
Send messages via multiple channels
Import data in bulk

Which Method to Use¶

Endpoint	Auth method
Search Contacts / Companies, Insert Message, the send endpoints	X-API-Key
REST API proxy (contacts, deals, conversations, tasks, …)	X-API-Key
Bulk leads, deals and contacts import	X-API-Key
Mobile API, attributed to an agent	User token from login
List Organizations, Check Subscription	User token from login

Note: a 401 response for an invalid API key is the expected, correct behavior.

Quick Start¶

Import the collection into Postman
Set the base variables (url, api_key, organization_id)
Run any X-API-Key endpoint — Search Contacts is a good first call
For user-attributed endpoints, run Login and the user_token variable is set for you