Skip to main content

​
Scopes

Each Gomry API key carries a scope map that controls which resources it can access and at what level. Scopes are configured per-resource and per-action, letting you create keys with exactly the access an integration needs.

​
Available Actions

ActionDescription
noneNo access. Requests to this resource return 403 insufficient_scope.
readRead-only access (GET requests).
writeFull access (GET, POST, PATCH, PUT, DELETE). Implies read.

​
Available Resources

contacts, events, experiences, attendees, ticket_classes, and applications support write. All other resources are read-only — selecting read is sufficient to use every endpoint listed.
ResourceEndpointsSupported actions
eventsGET/POST /v1/events, GET/PATCH /v1/events/:idnone, read, write
experiencesGET/POST /v1/experiences, GET/PATCH /v1/experiences/:id, GET/POST /v1/experiences/:id/recurrences, GET/PATCH/DELETE /v1/experiences/:id/recurrences/:idnone, read, write
attendeesGET/POST /v1/events/:id/attendees, GET/PATCH/DELETE /v1/events/:id/attendees/:idnone, read, write
ticket_classesGET/POST /v1/events/:id/ticket-classes, GET/PATCH/DELETE /v1/events/:id/ticket-classes/:idnone, read, write
contactsGET/POST /v1/contacts, GET/PATCH/DELETE /v1/contacts/:idnone, read, write
applicationsGET /v1/applications, GET/PATCH /v1/applications/:id, GET /v1/contacts/:id/applicationsnone, read, write
formsGET /v1/forms, GET /v1/forms/:idnone, read
listsGET /v1/lists, GET /v1/lists/:id, GET /v1/lists/:id/contactsnone, read
custom_fieldsGET /v1/custom-fields, GET /v1/custom-fields/:idnone, read
paymentsGET /v1/payments, GET /v1/payments/:idnone, read
Some endpoints depend on multiple resources. For example, GET /v1/lists/:id/contacts requires both lists:read and contacts:read because the response exposes contact records. Application responses include a resolved applicant object (email, first/last name) — this is part of applications:read, there is no separate scope for it. Each field is null when no linked record (application, user, contact, or a name/email-tagged answer) supplies it. See List Applications. API keys created before events:write shipped are capped at events:read for backwards compatibility — to enable event creation on a legacy key, edit it in the dashboard and select write. The same cap applies to experiences:write, attendees:write, ticket_classes:write, and applications:write: legacy keys must be opted in explicitly so a key sitting in someone’s .env cannot silently start mutating tickets, ticket classes, or applications when the write endpoints ship.

​
Configuring Scopes on a Key

When creating a key in Organization Settings → API Keys, the scope picker lets you set each resource to none, read, or write. Scopes can be updated later from the same screen without rotating the key. API keys created before scopes existed are treated as having full access (write on every resource) for backwards compatibility. We recommend tightening these legacy keys to the minimum scopes their integration actually needs.

​
Insufficient Scope Errors

If a request hits an endpoint the key isn’t authorized for, the API returns: 
{
  "error": "insufficient_scope",
  "message": "This API key does not have 'read' access to 'payments'.",
  "required_scope": "payments:read"
}
Status: 403 Forbidden. The fix is to grant the missing scope from the dashboard or use a different key.

​
Recommendations

  • Principle of least privilege. Start with none everywhere, then enable only what your integration needs.
  • Use separate keys per integration. A CRM sync needs contacts:read, lists:read, custom_fields:read. A finance reconciliation job needs payments:read. Don’t share keys.
  • Rotate periodically. Create a new key with the desired scopes, switch over, then revoke the old one.