API Keys

API Keys let you access EzPulze from your own applications. With an API key, your website, CRM, or automation tool can send WhatsApp messages, manage contacts, update leads, and more — all programmatically.

📸

Screenshot: API Keys list page showing table with key name, key preview, scopes, last used date, status toggle, and action buttons

api-keys-list.png

1. Go to Developer Tools → API Keys from the sidebar
2. Capture the full page showing the API keys table with several keys in different states
Save to: static/img/screenshots/developer-tools/api-keys/api-keys-list.png

API keys list

The list page shows all your API keys in a table:

Column	Description
#	Row number
Name	Key name with optional scope group label (e.g., "Broadcast Manager")
Key	Masked key showing only the prefix and last 4 characters (e.g., `sk_live_7f9a2b...a3f1`)
Scopes	Permission badges — shows the first 2, then "+X more" if there are additional scopes
Last Used	When the key was last used, or "Never" if unused
Status	Active (green) or Inactive (gray)
Actions	Action buttons

Actions

Action	Description
Toggle Active/Inactive	Enable or disable the key without deleting it
Regenerate	Generate a new key value (the old key stops working immediately)
View Usage Stats	See message delivery statistics for this key
Edit	Change the key name, scopes, or advanced settings
Delete	Permanently remove the key

Pagination

You can display 10, 25, or 50 keys per page. Columns are sortable by name and status.

Creating an API key

Click the Create API Key button to open the creation dialog.

📸

Screenshot: Create API Key dialog showing name field, permission configuration options, scope group dropdown, and advanced settings

create-api-key-dialog.png

1. Click "Create API Key"
2. Fill in the key name
3. Select a scope group from the dropdown
4. Expand Advanced Settings to show IP whitelist, rate limit, and expiration fields
5. Capture the full dialog
Save to: static/img/screenshots/developer-tools/api-keys/create-api-key-dialog.png

Key name

Give your key a descriptive name so you can identify it later — for example, "Website Contact Form", "CRM Integration", or "n8n Automation".

Permission configuration

You have two ways to set permissions:

Option 1: Scope groups (Recommended)

Select a predefined scope group that bundles the right permissions for common use cases:

Scope Group	Included Permissions	Best for
Broadcast Manager	Send broadcasts, read templates, read contacts	Sending bulk messages from external tools
Contact Manager	Full contact access, read leads	CRM integrations that sync contacts
Lead Manager	Full lead access, read contacts	Lead management integrations
Message Sender	Send broadcasts, read templates	Simple message-sending integrations
Read Only	Read broadcasts, contacts, leads, templates	Reporting and analytics tools
Full Access	All permissions for all resources	Complete system integrations
Webhook Automation	Chatbot flow webhooks, read contacts	Triggering chatbot flows from external systems

When you select a scope group, the included permissions are shown below the dropdown.

Option 2: Individual scopes (Advanced)

Select specific permissions by checking individual scopes grouped by resource:

Resource	Available Actions
Broadcast	Create, Read, Send, Delete, All
Contacts	Create, Read, Read All, Update, Delete, All
Leads	Create, Read, Read All, Update, Assign, Delete, All
Template	Read, Create, Update, Delete, All
Chatbot Flows	Webhook

You must select at least one scope.

📸

Screenshot: Individual scopes selection showing checkboxes grouped by resource (Broadcast, Contacts, Leads, Template, Chatbot Flows)

individual-scopes.png

1. In the Create API Key dialog, select "Select individual scopes (Advanced)"
2. Check a few scopes from different resource groups
3. Capture the scope checkboxes
Save to: static/img/screenshots/developer-tools/api-keys/individual-scopes.png

Advanced settings

Expand the Advanced Settings panel to configure optional security features:

Setting	Description	Default
Allowed IP Addresses	Restrict key usage to specific IP addresses. Enter one IPv4 address per line. Leave empty to allow all IPs.	All IPs allowed
Rate Limit (requests per hour)	Maximum number of API requests per hour. Leave empty for no limit.	1,000/hour
Expiration Date	Set an expiration date after which the key stops working. Leave empty for no expiration.	No expiration

Saving your API key

After clicking Create, the dialog shows your full API key in a yellow warning box.

📸

Screenshot: API key created successfully showing the full key in a yellow warning box with copy button and the message 'This is the only time you'll see the full API key'

api-key-created-warning.png

1. After creating a key, capture the warning box showing the full API key with the copy button
Save to: static/img/screenshots/developer-tools/api-keys/api-key-created-warning.png

Save your key immediately

This is the only time you'll see the full API key. Copy it and store it securely. If you lose it, you'll need to regenerate a new key.

Click the Copy button to copy the key to your clipboard, then click Done to close the dialog.

Editing an API key

Click the Edit action on any key to modify:

Key name
Permission configuration (scope group or individual scopes)
Advanced settings (IP whitelist, rate limit, expiration)

info

Editing a key does not change the key value itself. The existing key continues to work with the updated permissions.

Regenerating a key

If your key is compromised or you need a new value:

Click Regenerate from the actions menu
Confirm the action
The old key is immediately revoked
A new key is displayed — copy it and store it securely

Usage statistics

Click View Usage Stats to see how your API key has been performing.

📸

Screenshot: Usage Statistics dialog showing metric cards for Total Messages, Sent, Delivered, Read, Failed, Last Message, and progress bars for Delivery Rate and Read Rate

usage-stats-dialog.png

1. Click "View Usage Stats" on an API key that has been used
2. Capture the dialog showing all metric cards and the delivery/read rate progress bars
Save to: static/img/screenshots/developer-tools/api-keys/usage-stats-dialog.png

Metric	Description
Total Messages	Total number of messages sent using this key
Sent	Messages successfully sent to WhatsApp
Delivered	Messages delivered to the customer's phone
Read	Messages read (opened) by the customer
Failed	Messages that failed to send
Last Message	Date and time of the most recent message
Delivery Rate	Percentage of messages that were delivered or read
Read Rate	Percentage of messages that were read

API documentation

EzPulze includes a built-in API documentation page that generates ready-to-use code examples based on your API key and permissions.

📸

Screenshot: API Documentation page showing authentication section, broadcast API with auto-generated payload, and code examples in cURL and JavaScript

api-docs-page.png

1. Navigate to the API Documentation page (accessible from the API Keys section)
2. Select a broadcast from the dropdown to see auto-generated payloads
3. Capture the page showing the authentication section and broadcast API examples
Save to: static/img/screenshots/developer-tools/api-keys/api-docs-page.png

What's included

The documentation page shows endpoints based on your key's scopes:

Section	Available when	What it shows
Authentication	Always	How to use your API key, base URL
Broadcast API	Broadcast scope	Send messages — with a template picker that auto-generates the payload
Contacts API	Contacts scope	Create, read, update contacts
Leads API	Leads scope	Create, read, assign leads
Templates API	Template scope	List available templates
Error Codes	Always	Common error codes and meanings
Rate Limits	Always	Your key's rate limit and response headers

Broadcast payload generator

Select a broadcast (template) from the dropdown, and the documentation page automatically generates the complete API payload — including:

Template parameters (header, body, URL)
Media references (auto-populated if saved)
Button payloads (quick reply buttons)
Carousel cards (if applicable)
Product configuration (SPM/MPM templates)

Each example includes both cURL and JavaScript code with a Copy button.

Error codes

Code	Meaning
401	Unauthorized — invalid or missing API key
403	Forbidden — key doesn't have the required scope
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — something went wrong on the server

Security best practices

Use scope groups — Give each key only the permissions it needs
Set IP restrictions — If your integration runs from known servers, whitelist their IPs
Set expiration dates — For temporary integrations, set an expiry
Regenerate compromised keys — If a key is leaked, regenerate it immediately
Use separate keys — Create different keys for different integrations, so you can revoke one without affecting others
Never share keys in code — Store keys in environment variables, not in source code

Tips

The key prefix (sk_live_...) is used for quick identification — you can safely share the prefix without exposing the full key
If an API key is inactive, all requests using it will be rejected with a 401 error
Usage stats only count messages sent through the Broadcast API — not messages sent from the EzPulze UI
Use the API documentation page to test your integration — it generates exact payloads with your real templates

API keys list​

Actions​

Pagination​

Creating an API key​

Key name​

Permission configuration​

Option 1: Scope groups (Recommended)​

Option 2: Individual scopes (Advanced)​

Advanced settings​

Saving your API key​

Editing an API key​

Regenerating a key​

Usage statistics​

API documentation​

What's included​

Broadcast payload generator​

Error codes​

Security best practices​

Tips​