Authentication

API key authentication, scopes, and rate limits.

All service-to-service requests to PlatformXe are authenticated using API keys. There are no session cookies or OAuth flows for API access.

Getting an API key

curl -X POST https://platformxe.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company",
    "email": "dev@example.com",
    "password": "your-secure-password"
  }'

{
  "success": true,
  "data": {
    "organizationId": "org_abc123",
    "apiKey": "pxk_dev_abc123..."
  }
}

The raw API key is only shown once in the registration response. Store it securely — it cannot be retrieved later.

You can also sign up through the PlatformXe portal to manage your keys via the web dashboard. Free accounts start on the Starter plan with generous usage limits for development and testing.

Passing your API key

Include your key in either of these headers:

x-api-key: pxk_live_your_api_key_here

Authorization: Bearer pxk_live_your_api_key_here

Both are equivalent. Use whichever fits your HTTP client.

Key prefixes

Prefix	Environment	Description
`pxk_live_`	Production	Real requests, billed usage
`pxk_test_`	Sandbox	No side effects, no billing

Test keys hit the same API but skip external provider calls. Use them for integration testing without incurring costs.

Scopes

Each API key has one or more scopes that control what it can access:

Scope	Access
`messaging:send`	Email, SMS, WhatsApp dispatch
`storage:upload`	File upload
`storage:read`	File retrieval and listing
`storage:delete`	File deletion
`webhooks:manage`	Webhook CRUD
`templates:read`	Template retrieval
`templates:write`	Template creation and updates
`permissions:check`	Permission checks, resolve, role/module reads
`permissions:manage`	Role, override, policy CRUD, federation mutations
`permissions:audit`	Audit log queries and export
`identity:resolve`	Identity resolution lookups
`events:manage`	Event subscription CRUD
`events:read`	Event subscription reads
`exports:create`	Data export
`domains:manage`	Sending domain management

Follow the principle of least privilege. Create separate keys for separate services, each with only the scopes it needs.

Rate limits

Rate limits are enforced per API key, per scope tier:

Scope tier	Limit
`permissions:check` (check, resolve, batch)	5,000 requests/hr
`permissions:manage` (CRUD mutations)	500 requests/hr
`permissions:audit` (logs, export)	100 requests/hr
Default (all other routes)	1,000 requests/hr

When you exceed the limit, the API returns a 429 status with a RATE_LIMITED error code. The Retry-After header indicates how many seconds to wait.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 42 seconds."
  }
}

Key rotation

You can rotate an API key in the portal without downtime:

Navigate to Settings > API Keys.
Click Rotate on the key you want to replace.
A new key is generated immediately. The old key enters a grace period (24 hours by default) during which both keys are valid.
Update your application to use the new key.
After the grace period, the old key is automatically revoked.

During the grace period, both the old and new keys are accepted. This allows zero-downtime rotation across distributed services.