Authentication and access

Use Authorization: Bearer YOUR_KEY on every request. Keep credentials in your backend secret store. Never embed them in a browser, mobile client, prompt, or agent tool output.

Ruut uses service applications with independent, revocable keys. An account administrator creates applications and keys in Settings → Developers; follow the quickstart. The UI supports scope selection, explicit inbox grants, expiry, application disablement, and key revocation. Secrets are shown once. Management routes require an account administrator; service keys cannot manage their own grants. Legacy user tokens and support app sessions do not authenticate v2.

Scope	Access
`connections:read`	Inspect granted channel connections
`conversations:read`	Read conversations in granted inboxes
`messages:read`	Read public messages
`messages:write`	Reply to an eligible conversation
`media:read`, `media:write`	Read authorized attachments and upload media
`contacts:read`, `contacts:write`	Read and manage contacts and identities
`conversations:write`	Start conversations and update status
`handoffs:write`	Transfer response ownership
`calls:read`, `calls:write`	Read, start, and control voice calls
`notes:read`, `notes:write`	Read and create internal notes
`contact_sessions:write`	Issue and revoke restricted customer sessions
`customer_messages:write`	Permit customer ingress through a contact session
`webhooks:manage`	Manage subscriptions, secrets, and delivery replay
`credentials:manage`	Issue and revoke credentials within the caller's existing grants

Each key has explicit inbox grants. New inboxes are not granted automatically. Private support notes and internal activity messages are excluded. Expiry, revocation, account suspension, application disablement, and deletion of its configured bot prevent further use. Sandbox credentials are rejected until an isolated sandbox is implemented.

Rotate by issuing a replacement key, updating your secret store, and revoking the old key after your workers have switched. Rate limits apply independently to each key. Read the response headers and respect Retry-After.

Customer sessions

Your backend issues a session with POST /api/v2/contact-sessions, specifying a contact, explicit conversation IDs, allowed permissions, and a lifetime of 60–3,600 seconds. Session permissions must be a subset of the issuing key. The customer uses the returned bearer token to read those conversations and submit messages to API or website chat connections. Sessions cannot access internal notes, send staff messages, or manage credentials and subscriptions. Expiry, session revocation, or revoking its issuing key ends access.

Programmatic key management

A key with credentials:manage can list its application and manage keys under /api/v2/applications/{application_id}/keys. New scopes, inbox grants, and expiry cannot exceed the issuing key. Creating an initial application and first administrator credential remains in the authenticated settings UI.