Authentication

The Connexease Gateway uses API keys to verify your identity on every outbound request. When the Gateway forwards events back to your server, it uses a webhook secret you define — so both directions are protected without any extra setup on your end.

Credentials at a glance

Credential	Prefix	Where it belongs	Used for
API key	`sk_`	Your backend	Sending messages through `/v1/wa/message`
Secret key	`sk_`	Your backend	Public API endpoints and your Embedded Signup session-token endpoint
Publishable key	`pb_`	Browser (safe to ship)	Initializing the Embedded Signup SDK
Webhook secret	—	Your backend	Verifying that inbound webhook requests came from the Gateway

The API key and the secret key share the sk_ prefix but are different credentials: the API key is issued per application under App → Developer → API Keys, while the secret key is organization-level. The secret key and the publishable key are both created under Dashboard → avatar menu (top right) → My Profile → Organization tab. The webhook secret is set under App → Developer.

API Key Authentication

Every request to /v1/wa/message must include your API key in the Authorization header. The Gateway checks this key before processing anything — rate limiting, billing, and message delivery all happen only after a valid key is confirmed.

Authorization: Bearer YOUR_API_KEY

Get your API key from the Connexease Gateway Dashboard → App → Developer → API Keys.

Never expose your API key in frontend JavaScript, mobile app code, or public repositories. Always make requests from your backend server.

Example

curl -X POST https://api.gateway.connexease.com/v1/wa/message \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "905321234567",
    "type": "text",
    "text": { "body": "Hello!" }
  }'

import requests

response = requests.post(
    "https://api.gateway.connexease.com/v1/wa/message",
    headers={
        "Authorization": "Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "messaging_product": "whatsapp",
        "to": "905321234567",
        "type": "text",
        "text": {"body": "Hello!"}
    }
)
print(response.json())

const response = await fetch('https://api.gateway.connexease.com/v1/wa/message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    to: '905321234567',
    type: 'text',
    text: { body: 'Hello!' }
  }),
});
console.log(await response.json());

req, _ := http.NewRequest("POST",
    "https://api.gateway.connexease.com/v1/wa/message",
    strings.NewReader(`{"messaging_product":"whatsapp","to":"905321234567","type":"text","text":{"body":"Hello!"}}`),
)
req.Header.Set("Authorization", "Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

Error Responses

If authentication fails, the Gateway returns one of the following errors before touching any other part of the pipeline:

Code	HTTP	Cause	Fix
`AUTH_002`	401	`Authorization` header missing entirely	Add the header to every request
`AUTH_003`	401	Not in `Bearer <token>` format	Ensure the `Bearer` prefix is present
`AUTH_001`	401	Key not found or expired	Verify the key in Dashboard → API Keys

Public API Authentication

The Public API (public-api.gateway.connexease.com) endpoints authenticate with a secret key (sk_), sent in the Authorization header as a Bearer token. The organization is always derived from the credential — you never pass organization_id separately.

Secret Key

A server-side secret used for the Analytics, Application, and Template endpoints. Send it as:

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The organization (and the secret’s identity) is derived from the key, so no organization_id is ever sent.

The secret key is not used for sending messages. Message delivery through /v1/wa/message uses the application-level API key described above. The secret key is for the Public API and for the server side of the Embedded Signup SDK, where it signs the short-lived session token your backend hands to the browser.

Creating a secret key

Go to Dashboard → avatar menu (top right) → My Profile → Organization tab → Secret Keys → Create Secret Key.

Field	Description
Key name	Optional label that helps you tell keys apart later — for example `Secret Key to Public API`.
Expires	`6 months`, `1 year`, `2 years`, `5 years`, `Never`, or `Custom` for a specific date.

The full key is shown only once, right after it is created. From then on the list displays only the last four characters. Copy it into your secret manager or environment variables before closing the dialog — a lost key cannot be recovered, only replaced.

An organization can hold more than one secret key. Issuing a separate key per integration means you can revoke a single one without taking the others down. Once a key expires or is revoked, requests using it fail with ORGANIZATION_SECRET_011.

The secret key grants full server-side access. Never expose it in frontend JavaScript, mobile apps, or public repositories — use it only from your backend.

curl -X GET "https://public-api.gateway.connexease.com/api/v1/wa/analytics/messages" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Used by: Get Messages, Get Business Profile, Update Business Profile, Create Template, Get Templates, Get Template Detail, and Update Template. Errors: ORGANIZATION_SECRET_010 (missing), ORGANIZATION_SECRET_011 (invalid).

Publishable Key

The publishable key (pb_) is the client-side credential used by the Embedded Signup SDK. Unlike the API key and the secret key, it is meant to be shipped in browser code: it identifies your organization when the SDK opens the Meta onboarding popup, and it cannot send messages or read Public API data on its own. An organization can have one publishable key, and it stays visible in the dashboard list after creation — there is no one-time reveal.

Creating a publishable key

Go to Dashboard → avatar menu (top right) → My Profile → Organization tab → Publishable Key → Create Publishable Key. A key name is optional — for example Publishable Key to Embedded Signup. Pass the key to the SDK when you initialize it:

init({ publishableKey: 'pb_xxxxxxxxxxxxxxxxxxxxxx' });

See Installation for the full setup.

Allowed Origins

Only requests coming from the origins on this list can use your publishable key. The list is managed in the same Organization tab, below the key sections.

http://localhost:3000 is added by default so local development works out of the box.
Add every other origin you launch the SDK from, with the full scheme — for example https://gateway.connexease.com.
Removing an origin asks for confirmation and takes effect immediately.

If the origin your site runs on is not on the allowed-origins list, Embedded Signup cannot be used — the flow is rejected before onboarding can complete.

Newly added origins can take up to 48 hours to be approved on Meta’s side. Until approval lands, the Meta popup may fail to open from that origin. If it still doesn’t work after 48 hours, email gateway@connexease.com with your organization name and the origin you added.

Securing Your Webhook Endpoint

When the Gateway forwards events to your server, it includes a secret in the Authorization header — the same secret you set in Dashboard → App → Developer → Webhook. This lets you confirm that the request genuinely came from the Gateway and not a third party. Your endpoint receives requests in this shape:

POST https://your-server.com/webhook
Content-Type: application/json
Authorization: Bearer YOUR_WEBHOOK_SECRET

{ ...event payload... }

Check this header at the top of your handler, before reading or acting on the payload. Respond with HTTP 200 immediately, then process the event asynchronously — the Gateway will retry if it doesn’t hear back within 5 seconds.

app.post('/webhook', (req, res) => {
  const auth = req.headers['authorization'];
  if (auth !== `Bearer ${process.env.WEBHOOK_SECRET}`) {
    return res.status(401).send('Unauthorized');
  }

  res.sendStatus(200);
  setImmediate(() => handleEvent(req.body));
});

@app.route('/webhook', methods=['POST'])
def webhook():
    auth = request.headers.get('Authorization', '')
    if auth != f"Bearer {os.environ['WEBHOOK_SECRET']}":
        return '', 401

    payload = request.get_json()
    threading.Thread(target=handle_event, args=(payload,), daemon=True).start()
    return '', 200

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("Authorization") != "Bearer "+os.Getenv("WEBHOOK_SECRET") {
        http.Error(w, "Unauthorized", http.StatusUnauthorized)
        return
    }
    body, _ := io.ReadAll(r.Body)
    w.WriteHeader(http.StatusOK)
    go handleEvent(body)
}

Use a strong, randomly generated string (minimum 32 characters) as your webhook secret. Set it in Dashboard → App → Developer → Webhook.

API Key Management

Creating and Revoking Keys

Keys are created and managed from Dashboard → App → Developer → API Keys. If a key is compromised, revoke it immediately and generate a new one — update your environment variables before restarting your service.

Best Practices

Pass keys via environment variables — never hardcode them in source files.
Enable secret scanning in your CI/CD pipeline to catch accidental commits.

Getting Started

Essentials

Credentials at a glance

API Key Authentication

Example

Error Responses

Public API Authentication

Secret Key

Creating a secret key

Publishable Key

Creating a publishable key

Allowed Origins

Securing Your Webhook Endpoint

API Key Management

Creating and Revoking Keys

Best Practices

​Credentials at a glance

​API Key Authentication

​Example

​Error Responses

​Public API Authentication

​Secret Key

​Creating a secret key

​Publishable Key

​Creating a publishable key

​Allowed Origins

​Securing Your Webhook Endpoint

​API Key Management

​Creating and Revoking Keys

​Best Practices

Credentials at a glance

API Key Authentication

Example

Error Responses

Public API Authentication

Secret Key

Creating a secret key

Publishable Key

Creating a publishable key

Allowed Origins

Securing Your Webhook Endpoint

API Key Management

Creating and Revoking Keys

Best Practices