Authentication

Every request to the eCommunicate API requires a Developer API key in the Authorization header.

The API uses a custom apiKey scheme. Pass your key directly in the Authorization header — no Bearer prefix, no Basic auth.

curl -X GET "https://api.payless4messaging.com/your-endpoint" \
  -H "Authorization: a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Your API key is a standard UUID:

a1b2c3d4-e5f6-7890-abcd-ef1234567890

Use this endpoint to obtain your API key using your account credentials. No existing API key is required — this is the recommended starting point for new integrations.

POST /payless4messaging-service/WhatsApp/authenticate/retrieveApiKey

Request body:

{
  "email": "user@example.com",
  "password": "your-password",
  "clientRef": "CLIENT001"
}

Response:

{
  "apiKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

curl -X POST "https://api.payless4messaging.com/payless4messaging-service/WhatsApp/authenticate/retrieveApiKey" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password", "clientRef": "CLIENT001"}'

POST /payless4messaging-service/WhatsApp/SystemUsers/generateAPIKey

Response:

{
  "token": "f6e5d4c3-b2a1-0987-6543-210fedcba987"
}

A 401 Unauthorized means the key the server received is not one it recognises. Before changing any code, confirm which key your account actually has — there are two ways to check, and they should agree.

Sign in to the eCommunicate web UI and open your API key settings. This shows the key currently active on your account, which is the value your integration must send.

Call the retrieve endpoint with your account credentials. It requires no existing API key, so it still works when every other call is returning 401:

curl -X POST "https://api.payless4messaging.com/payless4messaging-service/WhatsApp/authenticate/retrieveApiKey" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password", "clientRef": "CLIENT001"}'

If this call itself returns 401 with {"error": "Invalid credentials"}, the problem is your email, password or clientRef — not your API key.

Once you know the correct key, check the value your integration puts in the header. A valid key is a 36-character UUID; any other length means it was truncated or padded between your secret store and the request.

String apiKey = System.getenv("ECOMM_API_KEY");

if (apiKey == null || apiKey.isBlank()) {
    throw new IllegalStateException("ECOMM_API_KEY is not set");
}
apiKey = apiKey.trim();   // strip trailing newlines from files and shell exports

// Safe to log — never log the full key
logger.info("API key length={} suffix=...{}",
    apiKey.length(), apiKey.substring(apiKey.length() - 4));

Still stuck after both checks agree? Contact support@ecommunicate.co.za with the requestId from the error response. See Error Handling for the full response format.

Never hardcode your API key. Use environment variables or a secrets manager:

# .env (never commit this file)
ECOMM_API_KEY=a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Access in your code
# Node.js: process.env.ECOMM_API_KEY
# Python:  os.environ["ECOMM_API_KEY"]
# Java:    System.getenv("ECOMM_API_KEY")