Why service-scoped tokens
Each Connect service has its own permissions. A Live Chat token cannot send email; a Business Email token cannot mint chat sessions. In Developers, pick the service by name (for example Business Email). Issue the narrowest token for the job, rotate on a schedule, and revoke from Dashboard → Developers.
Create a token
- Confirm the product is enabled under Dashboard → Billing.
- Open Dashboard → Developers.
- Choose the service by display name (for example Business Email), environment (
liveortest), optional expiry, optional IP allowlist, and permissions. - Copy the plaintext secret immediately—it is shown once. Store it as an environment variable on your server or agent worker.
Authenticate requests
Authorization: Bearer <token>
# or
X-API-Key: <token>
Base URL (production): https://umneyconnect.com/apiSuccessful and failed calls return X-Request-ID. Rate limits on /api/v1/* are 600 requests/minute per API key (plus per-route IP limits). HTTP 429 includes Retry-After and X-RateLimit-* headers.
Key formats
| Service | Permissions | Example prefix (live) |
|---|---|---|
| Live Chat | chat:read, chat:write, visitors:read, webhooks:manage | umk_live_<prefix>_… |
| Business Email | email:send, email:read | umk_live_email_<prefix>_… |
| AI Agent | ai:invoke | umk_live_ai_<prefix>_… |
| Business Calling | voice:read | umk_live_voice_<prefix>_… |
| Marketing | marketing:send | umk_live_marketing_<prefix>_… |
| Automations | automations:manage | umk_live_automations_<prefix>_… |
| Transactional | transactional:send | umk_live_transactional_<prefix>_… |
| Commerce | commerce:read | umk_live_commerce_<prefix>_… |
| Analytics | analytics:read | umk_live_analytics_<prefix>_… |
In Dashboard → Developers, choose the service name (for example Business Email or Live Chat)—not an internal catalog code. Live Chat live keys use umk_live_<8>_<secret>. Other services (and Live Chat test) use umk_{env}_{suite}_<8>_<secret>.
Agent / Nest pattern
Give the agent a token for only the services it must call. Example: Nest Safety needs Live Chat session minting—create a Live Chat token with chat:write, store it as CONNECT_API_KEY, and never ship it to the mobile app.
# Server / agent environment
CONNECT_API_BASE=https://umneyconnect.com/api
CONNECT_API_KEY=umk_live_… # Live Chat only
# Agent workflow
# 1. Read /llms.txt
# 2. Open /developers/live-chat for endpoint details
# 3. Call POST /v1/chat/sessions with the token
# 4. Return chatUrl to the end-user clientErrors
{
"statusCode": 403,
"error": "Forbidden",
"message": "API key lacks required scope: chat:write",
"requestId": "…"
}Common causes: missing Billing entitlement, wrong product token, missing scope, IP allowlist miss, or expired key. Rotate from Dashboard → Developers without changing your integration code beyond the secret value.