API Keys
Manage and generate API keys to enable external applications to securely interact with the system. These keys provide controlled access to specific functionalities, ensuring secure integration with third-party tools or services.
Navigate to Settings → API Keys to manage API access.
Page Layout
The API Keys page has two tabs:
| Tab | Purpose |
|---|---|
| API Keys | Create and manage API tokens |
| API Roles | Define permission sets that can be assigned to API keys |
API Keys Tab
Viewing API Keys
The API Keys list displays all generated tokens:
| Column | Description |
|---|---|
| API Key | The token value (used for authentication) |
| Description | Human-readable description of what this key is used for |
| API Name | The API role assigned to this key |
| Owner | User who created the key (name and email) |
| Allowed IPs | IP restrictions if configured |
| Last Accessed | When the key was last used for an API call |
| Status | Green checkmark indicates active |
| Actions | Toggle status, Edit, Delete |
Page Controls
- Create an API Key - Generate a new API token
- Show entries - Control how many keys are displayed per page
- Search - Filter keys by any column value
Creating an API Key
- Click Create an API Key
- The system generates a new API token and opens the settings modal
- Configure the key settings (see below)
- Click Update to save
The generated API key is displayed in the list and can be viewed or copied at any time.
API Key Settings
When creating or editing an API key, configure these fields:
| Field | Description |
|---|---|
| Description | Required. Descriptive name for this key (e.g., "Zapier Integration", "CRM Sync") |
| Rate limit | Allowed number of requests per minute. Default is 60. Adjust based on integration needs. |
| API Roles | Required. Select the permission role this key uses. Determines what operations the key can perform. |
| Allowed IPs | Toggle to enable IP restrictions. When enabled, only requests from listed IPs are accepted. |
Rate Limit
The rate limit controls how many API requests this key can make per minute. The default is 60, but you can set this higher based on your server capacity and integration needs. High-volume integrations on powerful servers may use limits in the thousands.
Allowed IPs
When the Allowed IPs toggle is enabled:
- A text area appears to enter IP addresses
- Enter one IP address per line
- Only requests from listed IPs will be accepted
- Requests from other IPs receive an authentication error
For production integrations, always enable IP restrictions. This prevents unauthorized use even if the API key is compromised.
Managing API Keys
Edit a Key
- Click the Edit icon on the key row
- Modify settings in the modal
- Click Update
Toggle Status
Click the Status checkmark to enable or disable a key. Disabled keys reject all API requests.
Delete a Key
- Click the Delete icon (red trash)
- Confirm deletion
- The key is immediately revoked
Deleting or disabling an API key immediately stops all applications using that key. Ensure you update integrations before revoking access.
API Roles Tab
API Roles define what operations an API key can perform. Create roles with specific permissions, then assign those roles to API keys.
Viewing API Roles
| Column | Description |
|---|---|
| Role Name | Name of the permission role |
| Description | What this role is intended for |
| Actions | Edit, Delete |
Each role row has a Click to expand button to preview the assigned permissions.
Creating an API Role
- Click Add API Role
- Configure the role settings:
| Field | Description |
|---|---|
| Role Name | Required. Unique name for this role (e.g., "Contact Read Only", "Full Access") |
| Description | Optional. Describe what this role is for |
- Configure API Permissions (see below)
- Click Save
API Permissions
The permissions interface has two panels:
Left Panel - Modules: Scrollable list of API modules. Click a module to see its permissions.
Right Panel - Permissions: Checkboxes for individual operations within the selected module. Use Check All to grant all permissions for that module.
Available Modules
| Module | Controls |
|---|---|
| List Management | Create, view, edit, delete lists and list groups |
| Contact Management | Create, view, edit, delete contacts; import/export |
| Broadcast Management | Create, view, edit, delete broadcasts |
| Custom Fields | Manage custom field definitions |
| Suppression | Manage suppression lists |
| Actions | Manage triggers and automation actions |
| Bounce Addresses | Manage bounce mailbox configurations |
| FBL Addresses | Manage feedback loop addresses |
| Spintags | Manage content spinning tags |
| Bounce Rules | Configure bounce handling rules |
| Sending Domain | Manage sending domain settings |
| Broadcast Statistics | Access campaign statistics and reports |
| Logs | Access system and activity logs |
| User Management | Manage users (admin keys only) |
| Sending Nodes | Manage SMTP nodes |
| Web Forms | Manage subscription forms |
| Profile Fields | Manage contact profile fields |
| Groups | Manage list groups |
Example: List Management Permissions
| Permission | Description |
|---|---|
| Add New List | Create new contact lists |
| View List | View individual list details |
| Views Lists | List all lists |
| Edit | Modify list settings |
| Delete | Remove lists |
| Delete List Group | Remove list groups |
| Get List Groups | Retrieve list group data |
Role Examples
Read-Only Role:
- Views Lists, View List (List Management)
- View contacts (Contact Management)
- View statistics (Broadcast Statistics)
Contact Sync Role:
- All List Management permissions
- All Contact Management permissions
- Views Broadcasts (Broadcast Management)
Full Integration Role:
- All permissions across all modules
Managing API Roles
Edit a Role
- Click the Edit icon on the role row
- Modify name, description, or permissions
- Click Save
Changes affect all API keys using this role immediately.
Delete a Role
- Click the Delete icon (red trash)
- Confirm deletion
You cannot delete a role that is assigned to active API keys. First reassign or delete those keys.
Using the API
Authentication
Include your API key in the request header:
Authorization: Bearer YOUR_API_KEY
Or as a query parameter:
?api_token=YOUR_API_KEY
Base URL
https://your-mumara-domain.com/api/
Example Request
curl -X POST "https://your-domain.com/api/addList" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-d "name=My List&group_id=1"
Response Format
{
"success": true,
"data": { ... },
"message": "Operation completed successfully"
}
Rate Limiting
When a key exceeds its rate limit:
- HTTP 429 (Too Many Requests) is returned
- Response headers indicate when to retry:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706745600
Implement exponential backoff in your integration to handle rate limits gracefully.
Best Practices
Security
- Use IP restrictions for production keys
- Create separate keys for each integration (don't share keys between applications)
- Minimum permissions - Only grant permissions the integration actually needs
- Regular audits - Review keys and remove unused ones
- Never expose keys - Don't commit to version control or expose in client-side code
Organization
- Descriptive names - Use descriptions like "Zapier - Contact Sync" not "API Key 1"
- Role per purpose - Create specific roles rather than using one "full access" role
- Document integrations - Track which systems use which keys
Monitoring
- Check Last Accessed - Keys that haven't been used recently may be candidates for deletion
- Review logs - Monitor API activity for unusual patterns
- Test after changes - Verify integrations work after modifying roles
Troubleshooting
Authentication Failed (401)
Possible causes:
- Invalid API key
- Key disabled or deleted
- Incorrect Authorization header format
Solutions:
- Verify the key exists and is active
- Check header format:
Authorization: Bearer KEY - Create a new key if needed
Permission Denied (403)
Possible causes:
- API role doesn't include the requested operation
- Trying to access another user's resources
Solutions:
- Check the role's permissions for the module
- Add missing permissions to the role
- Verify you're accessing resources owned by the key's owner
IP Blocked (403)
Possible causes:
- Request from IP not in Allowed IPs list
- IP changed (VPN, proxy, cloud infrastructure)
Solutions:
- Add the requesting IP to Allowed IPs
- Disable IP restrictions for development/testing
- Use a static IP for production integrations
Rate Limited (429)
Possible causes:
- Too many requests within the minute window
Solutions:
- Implement request throttling
- Increase the key's rate limit
- Batch operations where possible
- Wait for the rate limit window to reset
Next Steps
- Application Settings - Configure application options
- Licensing - Manage licensing
- Webhooks - Configure event notifications