Your Team — Roles & Permissions

Overview

You won't be the only person running your assistant. Receptionists need to read conversations, managers need to change settings, bookkeepers need billing visibility — and nobody should have more access than their job needs. The platform handles this with four roles plus per-user permission overrides.

The four roles

Every team member (and every API token) has a role that grants a baseline set of permissions, tunable per user with overrides.

Role	Use for	Baseline
`owner`	Account holders, senior people	All permissions. Cannot be revoked. At least one owner per account required.
`manager`	Day-to-day operators, partner team members	Settings, knowledge, apps (create/duplicate/take live), credentials (view + edit), conversations, recordings, caller profiles. No user management, billing, branding, or profile deletion (all owner-only).
`staff`	Receptionists, front-of-house	Conversations, recordings, read-only settings and credentials, caller profiles. No editing of settings/knowledge/credentials, no billing.
`viewer`	Bookkeepers, auditors, oversight	Read-only conversation visibility.

Permission catalogue

Permission	What it gates	Default roles
`view_settings`	Listing apps via the API; settings visibility in the dashboard	owner, manager, staff
`edit_settings`	Update/delete an app, restore versions, web-chat config, voice and phone/calling configuration	owner, manager
`create_app`	Create apps	owner, manager
`publish`	Take assistants live and offline	owner, manager
`clone_app`	Duplicate an app	owner, manager
`view_billing`	All ledger and billing reads, plan listing, auto top-up reads (account-level too)	owner
`edit_billing`	Buy credits, cap top-up/remove, plan change/cancel/resume, auto top-up writes	owner
`view_credentials`	List credentials (app + account; never returns secret values), run credential tests	owner, manager, staff
`edit_credentials`	Add, replace or delete credentials (app + account)	owner, manager
`view_conversations`	Conversation visibility in the dashboard	owner, manager, staff, viewer
`edit_conversations`	Transcript edits in the dashboard	owner, manager, staff
`view_recordings`	Recording playback in the dashboard	owner, manager, staff
`download_recordings`	Recording download in the dashboard	owner, manager, staff
`manage_users`	Invite, remove, change roles and overrides; create and list customer accounts	owner
`view_caller_profiles`	List/read caller profiles, issues, analytics, CSV exports	owner, manager, staff
`edit_caller_profiles`	Update profiles, merge duplicates, update issues	owner, manager
`delete_caller_profile`	Right-to-be-forgotten deletion	owner
`enable_reviews`	Per-app review settings	owner
`manage_branding`	Logo, colours, business name; per-account branding	owner
`set_wholesale_rate`	Per-customer rate when a partner creates customer accounts	owner (partner only)
`partner_principal`	Marker — this user is the partner-side principal; bundled by the become-a-partner flow; used for routing + display logic	(set by become-a-partner)
`view_knowledge`	Knowledge reads	owner, manager
`edit_knowledge`	Knowledge writes (upload / delete content)	owner, manager
`manage_bookings`	Bookings tab, calendar connect, upcoming-bookings list	owner, manager
`manage_booking_config`	Semble booking config	none — opt-in `+manage_booking_config` only
`view_intakes`	Intake submissions (list + detail)	owner, manager
`view_workflow_runs`	Automation run history in the dashboard	owner, manager
`view_call_logs`	Third-party call log	owner, manager
`manage_workflows`	Automation authoring in the dashboard	owner
`manage_api_keys`	Mint / list / revoke scoped API keys	owner
`show_partner_cta`	"Become a partner" visibility + endpoint	none — opt-in `+show_partner_cta` only

A note on the conversation permissions: conversation, recording and import API endpoints are available to any signed-in member of the owning account; the view_conversations / edit_conversations / recording permissions govern what each member sees and can do in the dashboard.

Scope: permissions take effect within the token's account. A manager in one account can edit that account's apps (and its sub-accounts') but never another account's. See For Partners for how account hierarchy works.

Override syntax: when a user is invited or edited, overrides go in as an array — e.g. featureOverrides: ['+view_billing', '-edit_conversations']. + grants on top of the role's baseline; - revokes from it. Precedence is - over + over baseline.

Manage Team Members

Requires manage_users. All endpoints are account-scoped: you only see and affect users inside your own account (and its sub-accounts).

Invite creates the sign-in and the user record and emails the invitation. Role is one of owner | manager | staff | viewer; you cannot assign a role that outranks your own, nor grant permissions you don't hold.

Role changes are held to a two-way ceiling: the new role must not outrank yours, and you cannot act on a user whose current role outranks yours (so a manager can never demote an owner). Clearing a role requires owner rank (a missing role defaults to owner). The last owner of an account cannot be demoted.

Pause is a reversible suspend: { "paused": true } blocks the sign-in immediately (existing sessions lapse within the hour), { "paused": false } restores it; nothing is deleted. Email lookups (?email=) include the current paused state. Pausing is held to the same guards as removal.

Remove deletes the sign-in and the user record — access ends immediately. Guards: you cannot remove yourself; you cannot remove a user whose role outranks yours; the last owner of an account cannot be removed (assign another owner first). userId accepts the id returned by the list endpoint.

Changing permission overrides (the featureOverrides array) goes through the same PATCH /api/v1/users/{userId} — see the override syntax above. Setting a wholesaleRate on a user additionally needs set_wholesale_rate.

GET/api/v1/users?email=…# list / look up team membersmanage_users

POST/api/v1/users# invite: { email, role, sendInvite: true }manage_users

PATCH/api/v1/users/{userId}# change role/details: { role: "manager", … }manage_users

POST/api/v1/users/{userId}/pause# pause/resume sign-in: { paused: true|false }manage_users

DELETE/api/v1/users/{userId}# remove (offboarding)manage_users

curl 'https://api.everycallhandled.com/api/v1/users' \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -X POST 'https://api.everycallhandled.com/api/v1/users' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"email":"teammate@business.com","role":"staff","sendInvite":true}'

curl -X PATCH 'https://api.everycallhandled.com/api/v1/users/{userId}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"role":"manager"}'

curl -X POST 'https://api.everycallhandled.com/api/v1/users/{userId}/pause' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"paused":true}'

curl -X DELETE 'https://api.everycallhandled.com/api/v1/users/{userId}' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy-only. DELETE is destructive — run it from your own terminal with the sample above, not from the docs.

← Billing & Credits API Keys →