Description
n8n-nodes-civicrm
!n8n Community Node
!CiviCRM API v4
!TypeScript
Community Node for CiviCRM API v4 (Civi-Go compatible)
Developed and maintained by Ixiam Global Solutions.
This node enables full integration between n8n and CiviCRM API v4, supporting create/update/delete operations, smart field mapping, dynamic location types, and advanced filtering on GET operations.
—
About CiviCRM
CiviCRM is an open-source Constituent Relationship Management platform designed for nonprofits, NGOs, and advocacy organizations. It supports contact management, memberships, contributions, event registration, email marketing, case management, and reporting. CiviCRM integrates with WordPress, Drupal, and Joomla.
Download: https://civicrm.org/download
—
🚀 Installation
1. In your n8n instance, go to:
Settings → Community Nodes → Install
2. Enter the package name:
@ixiam/n8n-nodes-civicrm
3. Approve installation and enable Community Nodes.
4. If running n8n via Docker, restart/rebuild for the node to load.
—
🔐 Credentials
The node supports two authentication modes:
1. Standard API Key Authentication
Simple and reliable for most use cases.
| Field | Description |
|——-|————-|
| Base URL | Root URL of CiviCRM. Example: https://crm.example.org |
| API Token | Your API Key from CiviCRM (sent as X-Civi-Auth: Bearer ) |
2. JWT Authentication with Auto-Resolve (v3.0+)
Time-bounded tokens for enhanced security. Contact ID is automatically resolved from your API Key.
| Field | Description |
|——-|————-|
| Base URL | Root URL of CiviCRM |
| API Token | Your API Key (used to resolve Contact ID & generate JWT) |
| Enable JWT Auth | Toggle to enable time-bounded JWT tokens |
| JWT Header Mode | Where to send JWT (X-Civi-Auth recommended) |
#### How JWT Auto-Resolve Works
1. When making an API call, the node automatically:
– Resolves your Contact ID from your API Key
– Generates a time-bounded JWT token (1 hour default)
– Caches both for efficiency
2. The JWT is used for API requests, with automatic fallback to API Key if:
– JWT generation fails
– JWT returns empty results
– JWT expires
3. Zero manual configuration – Contact ID is detected automatically
> Note on warnings vs. results: When JWT auth is enabled but the token can’t be obtained (e.g. AuthX disabled or misconfigured on the CiviCRM side), the node still returns data — it silently retries the same request with the API Key. You’ll see a warning in the node’s output pane explaining why JWT wasn’t used, but the workflow does not fail and the query results are still shown. This is intentional: JWT failures never break a workflow, they only fall back to API Key auth and surface a non-blocking warning.
> Troubleshooting “JWT authentication could not be obtained (no token returned by CiviCRM)”: This message covers several distinct failures on the CiviCRM side (Contact lookup by API Key failed, or AuthxCredential.create was denied), so it doesn’t say which one occurred. The most common cause is a missing permission: the Contact that owns the API Key must have the “AuthX: Generate new JWT credentials for other users via the API” permission on their role — see JWT Setup Requirements above. To confirm which step is failing, call Contact.get (filtered by api_key) and AuthxCredential.create directly against your CiviCRM instance and check the HTTP status/response of each.
#### JWT Setup Requirements
CiviCRM Extensions & Settings:
- ✓ AuthX extension enabled (CiviCRM 5.48+)
- ✓ API Key assigned to a Contact record
- ✓ The Contact’s role has the “AuthX: Generate new JWT credentials for other users via the API” permission (
generate any authx credential) — under Administer → Users and Permissions → Permissions. Without it,AuthxCredential.createreturns403 Authorization failedand the node silently falls back to API Key auth. Note that having “Administrator”/administer CiviCRMdoes not grant this by itself — it must be checked explicitly for the role.
CiviCRM Authentication Configuration
The following settings must be enabled in CiviCRM’s Authentication configuration:
Administer → System Settings → Authentication
├─ AuthX Header Authentication: ✓ ENABLED
├─ AuthX XHeader Support: ✓ ENABLED
├─ Credential Types: Include 'jwt'
└─ XHeader Name: Set to 'X-Civi-Auth' (default)
Settings in civicrm.settings.php:
// Enable AuthX for JWT tokens
define('CIVICRMAUTHXXHEADERCRED', jsonencode(['jwt']));// Optional: Configure JWT signing keys (auto-generated)
// define('CIVICRMAUTHXSIGN_KEY', 'your-signing-key');
How to Enable:
1. Go to Administer → System Settings → Authentication
2. Find AuthX Settings section
3. Check: ✓ Enable X-Header Authentication
4. Check: ✓ JWT in X-Civi-Auth header
5. Verify Header name: X-Civi-Auth
6. Save configuration
#### JWT Token Rotation & Security
Token Lifetime & Auto-Refresh:
Security Best Practices:
| Action | Frequency | Reason |
|——–|———–|——–|
| Rotate API Keys | Every 90 days | Limits exposure window if compromised |
| Review AuthX Logs | Monthly | Detect unauthorized access attempts |
| Monitor JWT Usage | Real-time | Alert on unusual patterns |
| Update CiviCRM | As released | Includes security patches |
| Audit n8n Workflows | Quarterly | Verify only needed credentials used |
When to Regenerate Credentials:
How to Revoke Access Immediately:
Option 1: Disable JWT (n8n credential)
├─ Uncheck "Enable JWT Auth" toggle
└─ Node falls back to API Key (effective immediately)Option 2: Regenerate API Key (CiviCRM)
├─ Go to Contact record
├─ Regenerate API Key field
└─ Old JWT & API Key become invalid instantly
→ See AUTORESOLVESETUP.md”>JWTAUTORESOLVESETUP.md for detailed configuration
—
After entering credentials, click Test credentials to validate the connection.
Base URL Override (v3.3.0+)
One credential can target many CiviCRM instances that share the same API key. Set the node’s Base URL Override field, usually with an expression, and every request for that item goes to that URL instead of the credential’s Base URL.
| Field | Description |
|——-|————-|
| Base URL Override | Optional. Site root, without /civicrm. Example: ={{ $json.instance_url }} |
https:// added when no scheme is given. Only http:// and https:// are accepted; anything else fails that item (honors Continue On Fail).loadOptions) have no item context and always use the credential’s Base URL.> ⚠️ The credential’s API key is sent to whatever URL the override resolves to. Only feed it URLs your workflow controls (a fixed list, or a source only trusted people can edit).
—
📦 Supported Entities
The node includes full API v4 support for the following entities:
| Entity | Operations |
|——–|————|
| Contact | get, getMany, create, update, delete |
| Membership | get, getMany, create, update, delete |
| Group | get, getMany, create, update, delete |
| Relationship | get, getMany, create, update, delete |
| Activity | get, getMany, create, update, delete |
| Custom API Call | full custom API4 request |
—
🧩 Key Features
1. Dynamic Field Mapping
Supports any standard or custom field:
first_name = John
last_name = Doe
custom_45 = Blue
2. Smart Email, Phone & Address Mapping
Two ways to set location-aware fields:
(A) Simple fields
email = test@example.org
phone.mobile = 600123456
address.city = Barcelona
(B) Dynamic prefixes matched to CiviCRM Location Types
work.email = user@company.org
billing.address.postal_code = 80331
home.phone.phonetypeid = 2
3. Default Location Type selectors
If no prefix is used, default types are applied.
4. Birth Date Normalization
Accepted input formats:
Auto-normalized to YYYY-MM-DD.
5. GET MANY with JSON Filters
Example:
[
["first_name", "LIKE", "Ju%"],
["birth_date", ">", "1990-01-01"],
["gender_id", "IN", [1, 2]]
]
6. Custom API Call Mode
Example:
{
"entity": "Contact",
"action": "get",
"params": { "limit": 10 }
}
7. JWT Authentication with Auto-Resolve (v3.0+)
Enhanced security with time-bounded tokens:
Features:
Example Workflow:
Enable JWT in credential
↓
Make API call
↓
[Automatic]
├─ Resolve: Which Contact owns this API Key?
├─ Generate: Time-bounded JWT token
├─ Try: API call with JWT
└─ Fallback: If empty, retry with API Key
↓
Get results
Security Benefits vs API Key Only:
