API Authentication — Keys, Scopes, and Bearer Tokens

The WaMatrix API uses API keys for authentication. Every request must include your key in the Authorization header. You can generate API keys in your Reseller Dashboard and scope them to your full account or to individual workspaces.

Generating an API Key

Go to app.wamatrix.io (or your custom domain) and sign in to your reseller account.

Open API Settings

Navigate to Settings → API → API Keys.

Create a new key

Click New API Key.

Name your key

Enter a descriptive name for the key — for example, CRM Integration or n8n Automation — so you can identify it later.

Choose a scope

Select the appropriate scope:

Reseller — full access to all workspaces and reseller-level endpoints.
Workspace — access restricted to a single client workspace.

Generate and copy the key

Click Generate. Copy the key immediately — it is shown only once.

API keys are shown only once at creation time. Store them securely — for example, in an environment variable or a secrets manager. If you lose a key, revoke it and generate a new one.

Using Your API Key

Pass your API key as a Bearer token in the Authorization header of every request.

cURL

curl -X GET https://api.wamatrix.io/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.wamatrix.io/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(f"{BASE_URL}/workspaces", headers=headers)
print(response.json())

const fetch = require('node-fetch');

const API_KEY = process.env.WAMATRIX_API_KEY;
const BASE_URL = 'https://api.wamatrix.io/v1';

async function getWorkspaces() {
  const res = await fetch(`${BASE_URL}/workspaces`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  });
  const data = await res.json();
  console.log(data);
}

getWorkspaces();

<?php
$apiKey = getenv('WAMATRIX_API_KEY');
$baseUrl = 'https://api.wamatrix.io/v1';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/workspaces');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

API Key Scopes

Scope	Access Level	Use Case
`reseller`	Full access to all workspaces and reseller settings	Automation scripts managing multiple workspaces
`workspace`	Access to a single workspace’s contacts, messages, templates, and campaigns	Client-specific integrations

Revoking Keys

To revoke an API key, go to Settings → API → API Keys, find the key you want to remove, and click Revoke. Revoked keys stop working immediately. Generate a new key and update any integrations that relied on the revoked key.

Authentication Errors

HTTP Status	Error Code	Meaning
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	Valid key but insufficient scope for this endpoint
`429`	`rate_limited`	Too many requests — check the `Retry-After` header

Store API keys as environment variables (e.g. WAMATRIX_API_KEY) and never hard-code them in source files or commit them to version control.

Overview

Endpoints

API Authentication — Keys, Scopes, and Bearer Tokens

Generating an API Key

Using Your API Key

API Key Scopes

Revoking Keys

Authentication Errors

​Generating an API Key

​Using Your API Key

​API Key Scopes

​Revoking Keys

​Authentication Errors

Generating an API Key

Using Your API Key

API Key Scopes

Revoking Keys

Authentication Errors