Authentication¶

This document describes the authentication mechanism for the WhiteLabelCRO Integration API.

Base URL¶

https://api.whitelabelcro.com

API Key Authentication¶

All Integration API endpoints use API key authentication.

API keys are passed via the X-Api-Key header:

X-Api-Key: wlcro_live_92_abc123def456...

API Key Format¶

API keys follow this structure:

wlcro_live_{companyId}_{secret}

wlcro_ - Fixed prefix
companyId - Integer company ID
secret - Base64url-encoded 32 random bytes (no padding)

API Key Scopes¶

API keys can be assigned specific scopes that control endpoint access:

Scope	Description
`events:read`	Poll events via `GET /api/v1/events`
`webhooks:write`	Manage webhook subscriptions
`integrations:read`	Search clients and affiliates
`integrations:write`	Create leads, notes, appointments
`admin`	Administrative operations including test event creation

Scopes are stored as a comma-separated string in the API key record.

Authorization¶

Endpoints require specific scopes:

Scope Required	Typical Endpoints
`events:read`	`GET /api/v1/events`
`webhooks:write`	Webhook subscription endpoints
`admin`	`POST /api/v1/events/test`

Requests without the required scope return 403 Forbidden.

API Key Storage¶

Keys are stored securely: - Full key is never stored; only a SHA-256 hash with server-side pepper - Hash stored as VARBINARY(32) with unique index for fast lookup - Original key cannot be recovered; if lost, create a new key

Last Used Tracking¶

API key usage is tracked via LastUsedUtc timestamp. Updates are throttled to approximately once per 5 minutes per key to reduce write amplification.