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.

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 → Developers → API Keys → Create API Key. API keys are prefixed so you can tell them apart at a glance:

Prefix	Environment
`pk_`	Production
`sk_`	Staging / Development

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 pk_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 pk_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 pk_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 pk_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 Secret Key is provided via email. To request your key, please contact the Connexease Sales or Support team, or send an email request to abdullah@connexease.com. The organization (and the secret’s identity) is derived from the key.

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/public/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).

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 → Settings → Webhooks. 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 → Settings → Webhooks.

API Key Management

Creating and Revoking Keys

Keys are created and managed from Dashboard → Settings → 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

Use separate keys for production (pk_) and staging (sk_) environments.
Pass keys via environment variables — never hardcode them in source files.
Enable secret scanning in your CI/CD pipeline to catch accidental commits.

# .env.production
CONNEXEASE_API_KEY=pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# .env.staging
CONNEXEASE_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting Started

Essentials

API Key Authentication

Example

Error Responses

Public API Authentication

Secret Key

Securing Your Webhook Endpoint

API Key Management

Creating and Revoking Keys

Best Practices

​API Key Authentication

​Example

​Error Responses

​Public API Authentication

​Secret Key

​Securing Your Webhook Endpoint

​API Key Management

​Creating and Revoking Keys

​Best Practices

API Key Authentication

Example

Error Responses

Public API Authentication

Secret Key

Securing Your Webhook Endpoint

API Key Management

Creating and Revoking Keys

Best Practices