All integrations

Gorgias

BUSINESS · CRM & SUPPORT

Tickets, their messages, views, customers, and macros in the helpdesk they connected.

Connecting Gorgias in practice

Gorgias runs a leaky bucket over a 20-second window and gives an OAuth2 app twice the room of an API-key integration: 80 requests per 20 seconds against 40. Enterprise accounts get the same two figures over a 10-second window, so identical code runs twice as fast on one helpdesk as on another, and the budget is per account rather than per credential.

Scopes that draw scrutiny

  • customers:read Gorgias’s own description: email address, first name, last name, language, notes, and data received via integrations such as Shopify — so it reaches whatever the store has synced in.
  • customers:write Edits the customer record itself, which is the object other Gorgias automations key off.
  • users:write Users are the helpdesk’s own agents, so this changes staff accounts rather than customer data.
  • integrations:write Changes the connected integrations, which is how data reaches the helpdesk in the first place.

Rate limits

  • OAuth2 apps: 80 requests in a 20-second window.
  • API key integrations: 40 requests in a 20-second window.
  • Enterprise accounts: the same figures measured over a 10-second window.
  • Leaky bucket, so capacity replenishes continuously instead of resetting at a boundary.
  • 429 Too Many Requests with Retry-After in seconds, plus X-Gorgias-Account-Api-Call-Limit reporting used against limit, for example 10/80.

Who has to approve

A public app is submitted to Gorgias’s tech partnership team, which reviews that it works properly and is aligned with their expectations before it appears in the in-product App Store or the public listing. Gorgias publishes no timeline and contacts the developer with the result; a rejected app gets feedback rather than a queue position.

Worth knowing

  • The limit header is named X-Gorgias-Account-Api-Call-Limit because the bucket is per account: every integration on one helpdesk shares it, so your own traffic is not the only thing that exhausts it.
  • Moving a private API-key integration to a public OAuth app doubles the budget, which makes an authentication migration a throughput change as well.
  • Some ticket custom fields are system-managed — Gorgias names AI Agent Outcome and AI Intent — and can only be deleted by Gorgias internal apps, so an agent’s cleanup pass will fail on them.
  • Audit log event retention is capped at 12 months, so anything an integration needs to prove about its own past writes has to be mirrored elsewhere.

Checked against Gorgias rate limits (2026-09-29), OAuth2 scopes (2026-09-29), Submit app for review (2026-09-29), Audit log retention changelog (2026-09-29)

Acts as the person, not as itself

Each user connects their own account. Every call carries both identities — the agent and the person it is acting for — so the agent can never reach past what that individual can already do.

Credentials never touch the agent

Tokens live in the vault and attach server-side at call time. The agent holds a session, not a secret, and revoking access does not mean rotating a key.

Every call on the record

Who asked, which agent acted, which action ran, and the verdict that let it through — one audit trail across every integration, not one per vendor.

What an agent can do

Each action is granted on its own. An agent allowed to read is not thereby allowed to write, and the scope beside each row is what the acting user must have connected for it to run at all.

gorgias_delete_api_customersWRITE

Delete customers via DELETE /api/customers

customers:write
gorgias_delete_api_customers_by_customer_id_custom_fields_by_idWRITE

Delete customer custom field value via DELETE /api/customers/{customer_id}/custom-fields/{id}

customers:write
gorgias_delete_api_customers_by_idWRITE

Delete customer via DELETE /api/customers/{id}

customers:write
gorgias_delete_api_integrations_by_idWRITE

Delete integration via DELETE /api/integrations/{id}

integrations:write
gorgias_delete_api_jobs_by_idWRITE

Cancel job via DELETE /api/jobs/{id}

jobs:write
gorgias_delete_api_macros_by_idWRITE

Delete macro via DELETE /api/macros/{id}

macros:write
gorgias_delete_api_phone_voice_call_recordings_by_idWRITE

Delete voice call recording via DELETE /api/phone/voice-call-recordings/{id}

no provider scope
gorgias_delete_api_rules_by_idWRITE

Delete rule via DELETE /api/rules/{id}

rules:write
gorgias_delete_api_tagsWRITE

Delete tags via DELETE /api/tags

tags:write
gorgias_delete_api_tags_by_idWRITE

Delete tag via DELETE /api/tags/{id}

tags:write
gorgias_delete_api_teams_by_idWRITE

Delete team via DELETE /api/teams/{id}

users:write
gorgias_delete_api_tickets_by_idWRITE

Delete ticket via DELETE /api/tickets/{id}

tickets:write
gorgias_delete_api_tickets_by_ticket_id_custom_fields_by_idWRITE

Delete ticket custom field via DELETE /api/tickets/{ticket_id}/custom-fields/{id}

tickets:write
gorgias_delete_api_tickets_by_ticket_id_messages_by_idWRITE

Delete ticket message via DELETE /api/tickets/{ticket_id}/messages/{id}

tickets:write
gorgias_delete_api_tickets_by_ticket_id_tagsWRITE

Delete ticket tags via DELETE /api/tickets/{ticket_id}/tags

tickets:write
gorgias_delete_api_users_by_idWRITE

Delete user via DELETE /api/users/{id}

users:write
gorgias_delete_api_views_by_idWRITE

Delete view via DELETE /api/views/{id}

tickets:write
gorgias_delete_api_widgets_by_idWRITE

Delete widget via DELETE /api/widgets/{id}

integrations:write
gorgias_get_api_accountREAD

Get account via GET /api/account

account:read
gorgias_get_api_account_settingsREAD

List account settings via GET /api/account/settings

account:read
gorgias_get_api_by_file_type_download_by_domain_hash_by_resource_nameREAD

Download file via GET /api/{file_type}/download/{domain_hash}/{resource_name}

no provider scope
gorgias_get_api_custom_fieldsREAD

List custom fields via GET /api/custom-fields

custom_fields:read
gorgias_get_api_custom_fields_by_idREAD

Get custom field via GET /api/custom-fields/{id}

custom_fields:read
gorgias_get_api_customersREAD

List customers via GET /api/customers

customers:read
gorgias_get_api_customers_by_customer_id_custom_fieldsREAD

List customer custom fields values via GET /api/customers/{customer_id}/custom-fields

customers:read
gorgias_get_api_customers_by_idREAD

Get customer via GET /api/customers/{id}

customers:read
gorgias_get_api_eventsREAD

List events via GET /api/events

events:read
gorgias_get_api_events_by_idREAD

Get event via GET /api/events/{id}

events:read
gorgias_get_api_integrationsREAD

List integrations via GET /api/integrations

integrations:read
gorgias_get_api_integrations_by_idREAD

Get integration via GET /api/integrations/{id}

integrations:read
gorgias_get_api_jobsREAD

List jobs via GET /api/jobs

jobs:read
gorgias_get_api_jobs_by_idREAD

Get job via GET /api/jobs/{id}

jobs:read
gorgias_get_api_macrosREAD

List macros via GET /api/macros

macros:read
gorgias_get_api_macros_by_idREAD

Get macro via GET /api/macros/{id}

macros:read
gorgias_get_api_messagesREAD

List messages via GET /api/messages

tickets:read
gorgias_get_api_metric_cardsREAD

Search metric cards via GET /api/metric-cards

statistics:read
gorgias_get_api_metric_cards_by_slugREAD

Get metric card via GET /api/metric-cards/{slug}

statistics:read
gorgias_get_api_phone_voice_call_eventsREAD

List voice call events via GET /api/phone/voice-call-events

no provider scope
gorgias_get_api_phone_voice_call_events_by_idREAD

Get voice call event via GET /api/phone/voice-call-events/{id}

no provider scope
gorgias_get_api_phone_voice_call_recordingsREAD

List voice call recordings via GET /api/phone/voice-call-recordings

no provider scope
gorgias_get_api_phone_voice_call_recordings_by_idREAD

Get voice call recording via GET /api/phone/voice-call-recordings/{id}

no provider scope
gorgias_get_api_phone_voice_callsREAD

List voice calls via GET /api/phone/voice-calls

no provider scope
gorgias_get_api_phone_voice_calls_by_idREAD

Get voice call via GET /api/phone/voice-calls/{id}

no provider scope
gorgias_get_api_rulesREAD

List rules via GET /api/rules

rules:read
gorgias_get_api_rules_by_idREAD

Get rule via GET /api/rules/{id}

rules:read
gorgias_get_api_satisfaction_surveysREAD

List satisfaction surveys via GET /api/satisfaction-surveys

satisfaction_survey:read
gorgias_get_api_satisfaction_surveys_by_idREAD

Get satisfaction survey via GET /api/satisfaction-surveys/{id}

satisfaction_survey:read
gorgias_get_api_tagsREAD

List tags via GET /api/tags

tags:read
gorgias_get_api_tags_by_idREAD

Get tag via GET /api/tags/{id}

tags:read
gorgias_get_api_teamsREAD

List teams via GET /api/teams

users:read
gorgias_get_api_teams_by_idREAD

Get team via GET /api/teams/{id}

users:read
gorgias_get_api_ticketsREAD

List tickets via GET /api/tickets

tickets:read
gorgias_get_api_tickets_by_idREAD

Get ticket via GET /api/tickets/{id}

tickets:read
gorgias_get_api_tickets_by_ticket_id_custom_fieldsREAD

List ticket custom fields via GET /api/tickets/{ticket_id}/custom-fields

tickets:read
gorgias_get_api_tickets_by_ticket_id_messagesREAD

List ticket messages via GET /api/tickets/{ticket_id}/messages

tickets:read
gorgias_get_api_tickets_by_ticket_id_messages_by_idREAD

Get ticket message via GET /api/tickets/{ticket_id}/messages/{id}

tickets:read
gorgias_get_api_tickets_by_ticket_id_tagsREAD

List ticket tags via GET /api/tickets/{ticket_id}/tags

tickets:read
gorgias_get_api_usersREAD

List users via GET /api/users

users:read
gorgias_get_api_users_by_idREAD

Get user via GET /api/users/{id}

users:read
gorgias_get_api_viewsREAD

List views via GET /api/views

tickets:read
gorgias_get_api_views_by_idREAD

Get view via GET /api/views/{id}

tickets:read
gorgias_get_api_views_by_view_id_itemsREAD

List view items via GET /api/views/{view_id}/items

tickets:read
gorgias_get_api_widgetsREAD

List widgets via GET /api/widgets

integrations:read
gorgias_get_api_widgets_by_idREAD

Get widget via GET /api/widgets/{id}

integrations:read
gorgias_post_api_account_settingsWRITE

Create account setting via POST /api/account/settings

account:write
gorgias_post_api_custom_fieldsWRITE

Create custom field via POST /api/custom-fields

custom_fields:write
gorgias_post_api_customersWRITE

Create customer via POST /api/customers

customers:write
gorgias_post_api_integrationsWRITE

Create integration via POST /api/integrations

integrations:write
gorgias_post_api_jobsWRITE

Create job via POST /api/jobs

jobs:write
gorgias_post_api_macrosWRITE

Create macro via POST /api/macros

macros:write
gorgias_post_api_metric_cards_by_slug_feedbackWRITE

Create metric card feedback via POST /api/metric-cards/{slug}/feedback

statistics:read
gorgias_post_api_reporting_statsWRITE

Get statistic via POST /api/reporting/stats

statistics:read
gorgias_post_api_rulesWRITE

Create rule via POST /api/rules

rules:write
gorgias_post_api_rules_prioritiesWRITE

Update rules priorities via POST /api/rules/priorities

rules:write
gorgias_post_api_satisfaction_surveysWRITE

Create satisfaction survey via POST /api/satisfaction-surveys

satisfaction_survey:write
gorgias_post_api_searchWRITE

Search via POST /api/search

no provider scope
gorgias_post_api_stats_by_nameWRITE

Get legacy statistic via POST /api/stats/{name}

statistics:read
gorgias_post_api_stats_by_name_downloadWRITE

Download legacy statistic via POST /api/stats/{name}/download

statistics:read
gorgias_post_api_tagsWRITE

Create tag via POST /api/tags

tags:write
gorgias_post_api_teamsWRITE

Create team via POST /api/teams

users:write
gorgias_post_api_ticketsWRITE

Create ticket via POST /api/tickets

tickets:write
gorgias_post_api_tickets_by_ticket_id_messagesWRITE

Create ticket message via POST /api/tickets/{ticket_id}/messages

tickets:write
gorgias_post_api_tickets_by_ticket_id_tagsWRITE

Create ticket tags via POST /api/tickets/{ticket_id}/tags

tickets:write
gorgias_post_api_usersWRITE

Create user via POST /api/users

users:write
gorgias_post_api_viewsWRITE

Create view via POST /api/views

tickets:write
gorgias_post_api_widgetsWRITE

Create widget via POST /api/widgets

integrations:write
gorgias_put_api_account_settings_by_idWRITE

Update account setting via PUT /api/account/settings/{id}

account:write
gorgias_put_api_custom_fieldsWRITE

Update custom fields via PUT /api/custom-fields

custom_fields:write
gorgias_put_api_custom_fields_by_idWRITE

Update custom field via PUT /api/custom-fields/{id}

custom_fields:write
gorgias_put_api_customers_by_customer_id_custom_fieldsWRITE

Update customer custom field values via PUT /api/customers/{customer_id}/custom-fields

customers:write
gorgias_put_api_customers_by_customer_id_custom_fields_by_idWRITE

Update customer custom field value via PUT /api/customers/{customer_id}/custom-fields/{id}

customers:write
gorgias_put_api_customers_by_customer_id_dataWRITE

Update customer data via PUT /api/customers/{customer_id}/data

customers:write
gorgias_put_api_customers_by_idWRITE

Update customer via PUT /api/customers/{id}

customers:write
gorgias_put_api_customers_mergeWRITE

Merge customers via PUT /api/customers/merge

customers:write
gorgias_put_api_integrations_by_idWRITE

Update integration via PUT /api/integrations/{id}

integrations:write
gorgias_put_api_jobs_by_idWRITE

Update job via PUT /api/jobs/{id}

jobs:write
gorgias_put_api_macros_archiveWRITE

Bulk archive macros via PUT /api/macros/archive

macros:write
gorgias_put_api_macros_by_idWRITE

Update macro via PUT /api/macros/{id}

macros:write
gorgias_put_api_macros_unarchiveWRITE

Bulk unarchive macros via PUT /api/macros/unarchive

macros:write
gorgias_put_api_rules_by_idWRITE

Update rule via PUT /api/rules/{id}

rules:write
gorgias_put_api_satisfaction_surveys_by_idWRITE

Update satisfaction survey via PUT /api/satisfaction-surveys/{id}

satisfaction_survey:write
gorgias_put_api_tags_by_destination_tag_id_mergeWRITE

Merge tags via PUT /api/tags/{destination_tag_id}/merge

tags:write
gorgias_put_api_tags_by_idWRITE

Update tag via PUT /api/tags/{id}

tags:write
gorgias_put_api_teams_by_idWRITE

Update team via PUT /api/teams/{id}

users:write
gorgias_put_api_tickets_by_idWRITE

Update ticket via PUT /api/tickets/{id}

tickets:write
gorgias_put_api_tickets_by_ticket_id_custom_fieldsWRITE

Update ticket custom fields via PUT /api/tickets/{ticket_id}/custom-fields

tickets:write
gorgias_put_api_tickets_by_ticket_id_custom_fields_by_idWRITE

Update ticket custom field via PUT /api/tickets/{ticket_id}/custom-fields/{id}

tickets:write
gorgias_put_api_tickets_by_ticket_id_messages_by_idWRITE

Update ticket message via PUT /api/tickets/{ticket_id}/messages/{id}

tickets:write
gorgias_put_api_tickets_by_ticket_id_tagsWRITE

Update ticket tags via PUT /api/tickets/{ticket_id}/tags

tickets:write
gorgias_put_api_users_by_idWRITE

Update user via PUT /api/users/{id}

users:write
gorgias_put_api_views_by_idWRITE

Update view via PUT /api/views/{id}

tickets:write
gorgias_put_api_views_by_view_id_itemsWRITE

Update view items via PUT /api/views/{view_id}/items

tickets:write
gorgias_put_api_widgets_by_idWRITE

Update widget via PUT /api/widgets/{id}

integrations:write

Put Gorgias behind one governed endpoint.

Same permissions, same audit trail, whatever else you connect next.