Authentication Errors¶

This document helps diagnose and resolve authentication issues with the Integration API.

Error Types¶

401 Unauthorized¶

Returned when authentication is missing or invalid.

Common Causes: - Missing X-Api-Key header - API key format is invalid - API key does not exist - API key has been revoked

Resolution: Verify your API key is correct and active.

403 Forbidden¶

Returned when authentication succeeds but the operation is not permitted.

Common Causes: - API key lacks the required scope for the endpoint - Attempting to access another company's resource

Resolution: Verify your API key has the required scopes, or request a new key with appropriate scopes.

Common Causes¶

Missing API Key¶

The X-Api-Key header is required for all Integration API requests.

X-Api-Key: wlcro_92_abc123def456...

Invalid API Key Format¶

API keys must match the format: wlcro_{companyId}_{secret}

Example valid key: wlcro_92_abc123def456ghi789jkl012mno345

API Key Not Found¶

The key may have been deleted or never existed. Verify the key in the Admin Portal under Settings > Integrations > API Keys.

API Key Revoked¶

Revoked keys return 401 on all requests. Check the key status in the Admin Portal. If revoked, create a new key.

Insufficient Scopes¶

Each endpoint requires specific scopes:

Endpoint	Required Scope
`GET /api/v1/events`	`events:read`
`POST /api/v1/webhooks/subscriptions`	`webhooks:write`
`POST /api/v1/events/test`	`admin`
`GET /api/v1/integrations/clients/find`	`integrations:read`
`POST /api/v1/integrations/leads`	`integrations:write`

If your key lacks the required scope, create a new key with the needed scopes.

Diagnosis Steps¶

Verify Key Format¶

Check that your key starts with wlcro_ and contains the expected segments: - Prefix: wlcro_ - Company ID: numeric - Secret: alphanumeric string

Check Key Status¶

In the Admin Portal:

Navigate to Settings > Integrations > API Keys
Find your key by name
Verify isActive is true
Check revokedUtc is null

Verify Scopes¶

Compare your key's scopes against the endpoint requirements. If scopes are insufficient, create a new key.

Resolution¶

Generate New Key¶

If your key is invalid, revoked, or has insufficient scopes:

Go to Admin Portal > Settings > Integrations > API Keys
Click Create New Key
Enter a name and select required scopes
Copy the generated key immediately (shown only once)
Update your application configuration

Update Application Configuration¶

After obtaining a new key, update it in your integration: - Zapier: Reconnect the WhiteLabelCRO app with the new key - n8n/Make: Update the credential with the new key - Custom code: Update environment variable or secret store

Prevention¶

Key Management Best Practices¶

Use descriptive names (e.g., "Zapier Production", "n8n Staging")
Create separate keys for separate integrations
Revoke keys that are no longer needed
Monitor lastUsedUtc to identify unused keys
Store keys in secure credential storage, never in source code

Monitoring¶

Watch for 401/403 errors in your integration logs. Frequent auth failures may indicate: - Key rotation needed - Scope misconfiguration - Attempted access to wrong company's data