Create an API Key
- Open the Visito dashboard.
- Open Developers → API Keys.
- Click Create new API Key.
- Choose a clear name, such as
Order status syncorCRM automation. - Select only the scopes required by your integration.
- Copy the key immediately and store it securely.
Authorization Header
Send the credential as a bearer token:Scopes
Scopes are additive. A request succeeds only when the key has the scope required by that endpoint.Example
Idempotency
Send endpoints require anIdempotency-Key header. Use a stable value from your system, such as an order ID, payment ID, or CRM workflow run ID.
Status Codes
Retry Policy
- Retry
GETrequests after transient429,502, or503responses using exponential backoff and jitter. - Retry reply or template send requests only with the exact same body and the exact same
Idempotency-Key. - Do not retry
400,401,403,404, or409automatically. - If a
429response includeserror.details.retryAfterSeconds, wait at least that long.
Additional scopes
conversations:assignment:readconversations:assignment:writeconversations:handoffs:writeconversations:policy:writecrm:sales:readcrm:sales:writeknowledge:readknowledge:writemessages:readproperties:readreporting:readwebhooks:readwebhooks:write
ops:handoffs:create does not authorize the separate Ops API.
Action management permissions
These permissions are independent. Configuration access never implies execution or diagnostics. Existing keys and OAuth grants remain unchanged; a refresh token cannot add scopes.
Migration details.
Guest AI configuration permissions
- ai_settings:read: current guest personality/raw runtime inputs, photo limit and escalation policy.
- ai_settings:write: versioned updates to those existing settings.
Separate channel connection and management access
channels:read reads channels and connection attempts. channels:write retains only the existing versioned automatic-reply operation. New channels:connect:write creates temporary human-completed connection links, and new channels:manage:write manages activation/configuration, requested disconnects and supported provider maintenance. New operations recheck current admin ownership. Existing API keys and OAuth grants retain their exact scopes. Grant additional permissions explicitly, without widening old credentials. See channel contract and recovery.
Tickets and escalations
tickets:read discovers both types; tickets:write manages general tickets. conversations:handoffs:create initiates escalation; escalation management retains conversations:handoffs:write and assignment retains conversations:assignment:write. Context reads and sending permissions remain separate. Existing credentials and OAuth grants retain their exact scopes; explicitly grant new access. See the contract and agent workflow.