Allo

Authentication

Authenticate API requests using API keys

Updated on

All API requests require an API key passed in the Authorization header.

Header format

Authorization: Api-Key ak_live_your_key_here

You can also send the raw key on its own, with no prefix:

Authorization: ak_live_your_key_here

Generating API keys

  1. Go to Allo Settings > API
  2. Click Create API Key
  3. Select the scopes your integration needs
  4. Copy the key. It won't be shown again

API key scopes

Each API key has specific scopes that determine what operations it can perform.

ScopeDescription
CONVERSATIONS_READRead calls, SMS, and conversation history
CONVERSATIONS_WRITEEdit call summaries and archive or mark conversations
CRM_READGet and search people, companies, and deals, and list custom fields
CRM_WRITECreate and update people and companies, and create custom fields
CRM_DELETEDelete custom attributes on people and companies
SMS_SENDSend SMS and MMS
FAX_SENDSend faxes
WEBHOOKS_READ_WRITECreate and manage webhook configurations
PHONE_NUMBERS_READList phone numbers and their capabilities
PHONE_NUMBERS_WRITESave and publish call flows
USERS_READList team members and their roles
TAGS_READList available tags
TAGS_WRITECreate and delete tags, add and remove them on conversation items
NOTES_READRead conversation notes and person notes
NOTES_WRITECreate, edit, and delete notes
THREADS_READRead discussion threads and their comments
THREADS_WRITECreate threads and comments, edit comments, resolve threads
SUMMARY_TEMPLATES_READRead the team's call summary templates
SUMMARY_TEMPLATES_WRITECreate, update, and delete summary templates, and set a number's default
BILLINGAccess billing and subscription information
DIALING_QUEUE_READ_WRITEManage Power Dialer queues
AGENTS_READRead AI receptionist configuration, connected calendars, and voices
AGENTS_WRITEConfigure the AI receptionist, its prompt, its knowledge, and turn it on or off
INBOXES_READList your inboxes and teammates' inboxes, inbox suggestions, and a line's phone-menu options
INBOXES_WRITECreate, update, mute, and delete inboxes
PARTNERProvision and manage Allo accounts as a reseller. Granted manually to approved resellers, it cannot be self-issued

GET /v2/api/me requires no scope. Any valid key can call it, and its endpoints array is the authoritative list of what your key can reach.

Scope-to-endpoint mapping

Every documented endpoint and the scope it needs. If a call returns 403 with code API_KEY_INSUFFICIENT_SCOPE, the key is valid but missing the scope listed here.

Discovery

EndpointMethodRequired scope
/v2/api/meGETnone

Conversations

EndpointMethodRequired scope
/v2/api/conversationsGETCONVERSATIONS_READ
/v2/api/conversations/items/batchPOSTCONVERSATIONS_READ
/v2/api/conversations/items/searchPOSTCONVERSATIONS_READ
/v2/api/conversations/items/{id}GETCONVERSATIONS_READ
/v2/api/conversations/items/{id}/recordingGETCONVERSATIONS_READ
/v2/api/conversations/items/{id}/summaryPATCHCONVERSATIONS_WRITE
/v2/api/conversations/items/{id}/tagsPOSTTAGS_WRITE
/v2/api/conversations/items/{id}/tags/{tag}DELETETAGS_WRITE
/v2/api/conversations/notes/{id}DELETENOTES_WRITE
/v2/api/conversations/notes/{id}GETNOTES_READ
/v2/api/conversations/notes/{id}PATCHNOTES_WRITE
/v2/api/conversations/{contact_number}/actionPUTCONVERSATIONS_WRITE
/v2/api/conversations/{contact_number}/notesGETNOTES_READ
/v2/api/conversations/{contact_number}/notesPOSTNOTES_WRITE
/v2/api/conversations/{contact_number}/pinDELETECONVERSATIONS_WRITE
/v2/api/conversations/{contact_number}/pinPUTCONVERSATIONS_WRITE

CRM

EndpointMethodRequired scope
/v2/api/crm/attributesGETCRM_READ
/v2/api/crm/attributesPOSTCRM_WRITE
/v2/api/crm/attributes/{key}DELETECRM_DELETE
/v2/api/crm/attributes/{key}PATCHCRM_WRITE
/v2/api/crm/companies/attributesGETCRM_READ
/v2/api/crm/companies/attributesPOSTCRM_WRITE
/v2/api/crm/companies/attributes/{key}DELETECRM_DELETE
/v2/api/crm/companies/attributes/{key}PATCHCRM_WRITE
/v2/api/crm/companiesPOSTCRM_WRITE
/v2/api/crm/companies/searchPOSTCRM_READ
/v2/api/crm/companies/{id}GETCRM_READ
/v2/api/crm/companies/{id}PUTCRM_WRITE
/v2/api/crm/deals/searchPOSTCRM_READ
/v2/api/crm/deals/{id}GETCRM_READ
/v2/api/crm/peoplePOSTCRM_WRITE
/v2/api/crm/people/searchPOSTCRM_READ
/v2/api/crm/people/{id}GETCRM_READ
/v2/api/crm/people/{id}PUTCRM_WRITE
/v2/api/crm/people/{person_id}/notesGETNOTES_READ
/v2/api/crm/people/{person_id}/notesPOSTNOTES_WRITE
/v2/api/crm/people/{person_id}/notes/{note_id}DELETENOTES_WRITE
/v2/api/crm/people/{person_id}/notes/{note_id}PATCHNOTES_WRITE

Threads

EndpointMethodRequired scope
/v2/api/threadsGETTHREADS_READ
/v2/api/threadsPOSTTHREADS_WRITE
/v2/api/threads/comments/{comment_id}PATCHTHREADS_WRITE
/v2/api/threads/{id}GETTHREADS_READ
/v2/api/threads/{id}/commentsPOSTTHREADS_WRITE
/v2/api/threads/{id}/resolvePOSTTHREADS_WRITE
/v2/api/threads/{id}/unresolvePOSTTHREADS_WRITE

Inboxes

EndpointMethodRequired scope
/v2/api/inboxesGETINBOXES_READ
/v2/api/inboxesPOSTINBOXES_WRITE
/v2/api/inboxes/suggestionsGETINBOXES_READ
/v2/api/inboxes/{inbox_id}DELETEINBOXES_WRITE
/v2/api/inboxes/{inbox_id}PATCHINBOXES_WRITE
/v2/api/numbers/{number}/menu_optionsGETINBOXES_READ

SMS

EndpointMethodRequired scope
/v1/api/smsPOSTSMS_SEND
/v1/api/sms#francePOSTSMS_SEND
/v2/api/faxesPOSTFAX_SEND

Phone numbers and call flows

EndpointMethodRequired scope
/v2/api/numbersGETPHONE_NUMBERS_READ
/v2/api/numbers/{number}/agentGETAGENTS_READ
/v2/api/numbers/{number}/agentPATCHAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/files/{id}DELETEAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/websitesPOSTAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/websites/{id}DELETEAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/websites/{id}PATCHAGENTS_WRITE
/v2/api/numbers/{number}/agent/promptPUTAGENTS_WRITE
/v2/api/numbers/{number}/agent/statusPUTAGENTS_WRITE
/v2/api/numbers/{number}/call_flowGETPHONE_NUMBERS_READ
/v2/api/numbers/{number}/call_flow/draftGETPHONE_NUMBERS_READ
/v2/api/numbers/{number}/call_flow/draftPUTPHONE_NUMBERS_WRITE
/v2/api/numbers/{number}/call_flow/publishPOSTPHONE_NUMBERS_WRITE
/v2/api/numbers/{number}/default_summary_templatePUTSUMMARY_TEMPLATES_WRITE

AI receptionist

EndpointMethodRequired scope
/v2/api/calendarsGETAGENTS_READ
/v2/api/calendars/{id}GETAGENTS_READ
/v2/api/voicesGETAGENTS_READ

Summary templates

EndpointMethodRequired scope
/v2/api/summary_templatesGETSUMMARY_TEMPLATES_READ
/v2/api/summary_templatesPOSTSUMMARY_TEMPLATES_WRITE
/v2/api/summary_templates/{id}DELETESUMMARY_TEMPLATES_WRITE
/v2/api/summary_templates/{id}GETSUMMARY_TEMPLATES_READ
/v2/api/summary_templates/{id}PUTSUMMARY_TEMPLATES_WRITE

Tags

EndpointMethodRequired scope
/v2/api/tagsGETTAGS_READ
/v2/api/tagsPOSTTAGS_WRITE
/v2/api/tags/{id}DELETETAGS_WRITE

Users

EndpointMethodRequired scope
/v2/api/usersGETUSERS_READ
/v2/api/users/{id}GETUSERS_READ

Webhooks

EndpointMethodRequired scope
/v2/api/webhooksGETWEBHOOKS_READ_WRITE
/v2/api/webhooksPOSTWEBHOOKS_READ_WRITE
/v2/api/webhooks/event_typesGETWEBHOOKS_READ_WRITE
/v2/api/webhooks/{webhook_id}DELETEWEBHOOKS_READ_WRITE
/v2/api/webhooks/{webhook_id}GETWEBHOOKS_READ_WRITE
/v2/api/webhooks/{webhook_id}PUTWEBHOOKS_READ_WRITE

Analytics

EndpointMethodRequired scope
/v2/api/analytics/outboundPOSTCONVERSATIONS_READ
/v2/api/analytics/overviewPOSTCONVERSATIONS_READ

Dialing queues

EndpointMethodRequired scope
/v2/api/dialing-queues/currentGETDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/currentPATCHDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/currentPOSTDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/current/numbersDELETEDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/current/numbersPOSTDIALING_QUEUE_READ_WRITE

Partners

EndpointMethodRequired scope
/v2/api/partner/accountsPOSTPARTNER
/v2/api/partner/accounts/priceGETPARTNER
/v2/api/partner/accounts/{id}DELETEPARTNER
/v2/api/partner/accounts/{id}GETPARTNER
/v2/api/partner/creditGETPARTNER

White label

EndpointMethodRequired scope
/v2/api/partner/accounts/{account_id}/esimsPOSTPARTNER
/v2/api/partner/accounts/{account_id}/esims/offerGETPARTNER
/v2/api/partner/accounts/{account_id}/sender_idsGETPARTNER
/v2/api/partner/accounts/{account_id}/sender_idsPOSTPARTNER
/v2/api/partner/accounts/{account_id}/sender_ids/{id}GETPARTNER
/v2/api/partner/accounts/{id}/membersGETPARTNER
/v2/api/partner/accounts/{id}/membersPOSTPARTNER
/v2/api/partner/accounts/{id}/members/{member_id}DELETEPARTNER
/v2/api/partner/accounts/{id}/numbersPOSTPARTNER
/v2/api/partner/accounts/{id}/numbers/priceGETPARTNER
/v2/api/partner/accounts/{id}/resumePOSTPARTNER
/v2/api/partner/accounts/{id}/suspendPOSTPARTNER
/v2/api/partner/esims/{id}GETPARTNER
/v2/api/partner/esims/{id}/activation_codeGETPARTNER
/v2/api/partner/esims/{id}/revokePOSTPARTNER
/v2/api/partner/esims/{id}/tierPUTPARTNER
/v2/api/partner/esims/{id}/topupsPOSTPARTNER

Example request

curl -X GET "https://api.withallo.com/v2/api/conversations" \
  -H "Authorization: Api-Key ak_live_abc123def456"

Error responses

Invalid or missing key (401)

{
  "error": {
    "type": "authentication_error",
    "code": "API_KEY_INVALID",
    "message": "The API key provided is invalid or has been revoked.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://www.withallo.com/docs/guides/error-codes#api_key_invalid"
  }
}

Insufficient scope (403)

{
  "error": {
    "type": "permission_error",
    "code": "API_KEY_INSUFFICIENT_SCOPE",
    "message": "This API key lacks the 'CONVERSATIONS_READ' scope required for this endpoint.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "suggestion": "Create a new API key with the required scope at https://web.withallo.com/settings/api"
  }
}

Security

  • API keys are scoped to a single team
  • Keys can be revoked at any time from settings
  • Never expose keys in client-side code or public repositories
  • Use environment variables to store keys in your application