Skip to content

n8n Authentication

This document describes how to authenticate n8n with the WhiteLabelCRO Integration API.

Authentication Method

n8n uses API key authentication via the X-Api-Key header. This is the same authentication method used by Zapier, Make, and custom integrations.

In n8n, you configure credentials that include the API key, and n8n includes it with every API request to WhiteLabelCRO.

Obtaining an API key

Step 1: Create Key in Admin Portal

  1. Log in to your WhiteLabelCRO CRM
  2. Navigate to Settings > Integrations > API Keys
  3. Click Create New Key
  4. Enter a descriptive name (e.g., "n8n Production Workflows")
  5. Select required scopes (see below)
  6. Click Create
  7. Copy the generated key immediately

Critical: The full API key is displayed only once. Store it securely before closing the dialog.

Step 2: Required Scopes

For full n8n functionality, select these scopes: - events:read - Required for polling events or webhook triggers - integrations:read - Required for search operations - integrations:write - Required for create/update actions - webhooks:write - Required if managing webhook subscriptions programmatically

You may use a key with fewer scopes if you only need specific operations (e.g., read-only workflows).

Configuring Credentials in n8n

Creating a Credential

WhiteLabelCRO does not currently have a native n8n node. Use the HTTP Request node with Header Auth.

Using HTTP Request nodes:

  1. In n8n, open your workflow
  2. Add or edit an HTTP Request node
  3. Under Authentication, select Header Auth
  4. Click Create New Credential
  5. Set credential name (e.g., "WhiteLabelCRO API")
  6. Add header:
  7. Name: X-Api-Key
  8. Value: Paste your API key
  9. Click Save

Using the Credential

  1. In HTTP Request nodes, select the saved credential
  2. n8n will automatically include the X-Api-Key header with every request
  3. No need to manually set headers per node

Multiple Credentials

You can create multiple credentials in n8n for: - Different WhiteLabelCRO environments - Different API key scopes - Different clients (if you manage multiple CROs)

Each workflow can use a different credential.

Managing Credentials

Viewing Saved Credentials

In n8n:

  1. Click Credentials in the left sidebar
  2. Search for "WhiteLabelCRO" or your credential name
  3. View all saved credentials

Updating After Key Rotation

If you rotate or revoke an API key:

  1. Create a new API key in WhiteLabelCRO Admin Portal
  2. In n8n, go to Credentials
  3. Find the WhiteLabelCRO credential
  4. Click Edit
  5. Update the X-Api-Key value with the new key
  6. Click Save

All workflows using that credential will automatically use the new key.

Deleting Credentials

To remove a credential: 1. Go to Credentials in n8n 2. Find the credential 3. Click Delete

This does not revoke the API key in WhiteLabelCRO. To fully revoke access: 1. Delete the credential in n8n 2. Revoke the API key in WhiteLabelCRO Admin Portal

Security Considerations

Key Storage

  • n8n stores credentials encrypted in its database
  • Keys are transmitted over HTTPS only
  • Keys are not visible in workflow execution logs
  • Use n8n's credential sharing features carefully

Key Separation

Use separate API keys for: - Different n8n instances (production vs development) - Different workflow purposes - Different team members (if self-hosted)

This allows targeted revocation without disrupting all workflows.

Monitoring

Track API key usage in WhiteLabelCRO Admin Portal: - Check lastUsedUtc timestamp to confirm activity - Review rate limit consumption - Monitor for unexpected usage patterns

Revocation

If a key is compromised:

  1. Revoke the key immediately in WhiteLabelCRO Admin Portal
  2. All n8n requests will start failing (401 errors)
  3. Create a new key
  4. Update the credential in n8n with the new key

Troubleshooting

Invalid API Key Error

Symptom: 401 error in workflow execution

Check: - Key was copied completely (no truncation) - Key format is wlcro_live_{companyId}_{secret} - Key exists and is active in Admin Portal - Key has not been revoked

Resolution: - Re-copy the key from secure storage - If lost, create a new key - Update credential in n8n

Authentication Works Then Stops

Symptom: Previously working workflows return 401 errors

Cause: API key was revoked in WhiteLabelCRO Admin Portal

Resolution: - Verify key status in Admin Portal - Create new key if revoked - Update credential in n8n

Insufficient Permissions

Symptom: Authentication succeeds but specific operations fail with 403 errors

Cause: API key lacks required scope

Resolution: - Check which scope is required (see error message in workflow execution) - Create new key with additional scopes - Update credential in n8n - Cannot add scopes to existing keys

Wrong API Key Used

Symptom: Workflow accessing wrong WhiteLabelCRO account

Resolution: - Check which credential the HTTP Request node is using - Update node to use correct credential - Name your credentials clearly (e.g., "WhiteLabelCRO Production", "WhiteLabelCRO Dev")

Testing Credentials

Manual Test Request

To verify your credential works:

  1. Add HTTP Request node
  2. Set method: GET
  3. Set URL: https://your-api-url.com/api/v1/events?limit=1
  4. Select your WhiteLabelCRO credential
  5. Execute the node
  6. Should return 200 with event data (or empty array if no events)

Common Test Failures

  • 401: Invalid or revoked API key
  • 403: API key lacks events:read scope
  • 404: Incorrect API base URL
  • Connection timeout: Network or firewall issue

Best Practices

Naming Conventions

When creating API keys for n8n, use descriptive names: - ✅ "n8n Production - Full Access" - ✅ "n8n Dev - Read Only" - ❌ "n8n Key 1" - ❌ "Test"

Scope Principle

Grant only the scopes needed: - Read-only workflows (reporting): events:read, integrations:read - Write-only workflows (data entry): integrations:write - Full bidirectional sync: All scopes

Regular Audits

Periodically review: - Active API keys in WhiteLabelCRO Admin Portal - Saved credentials in n8n - Remove unused credentials and revoke unused keys

Self-Hosted Security

If running n8n self-hosted: - Use encryption key for credential storage - Restrict database access - Use environment variables for sensitive configuration - Implement access controls for n8n UI