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
Available Resources
contacts, events, experiences, attendees, ticket_classes, applications, and spaces support write. checkout is the one resource that supports write but not read — see Commerce scopes. Every other resource is read-only, and selecting read is sufficient to use each endpoint listed.
Commerce scopes
catalog and checkout power the Agentic Commerce surface and behave differently from every other scope on this page. Both are off by default on every key, including keys created before scopes existed — the legacy full-access rule does not extend to them, and they must be granted explicitly.
These two are not organization-scoped.catalog is a cross-organization read: one key returns live public events from every organizer on Gomry. Granting it to an organizer’s own integration would silently hand that integration a platform-wide catalog.checkout goes further — it sells an arbitrary organizer’s tickets and takes payment against their Stripe account. It is the most privileged scope in this API.
checkout supports write and not read: reading a session is part of the same capability, and a read-only checkout scope would grant access to buyer details without any ability to act on them.
The checkout scope alone is not sufficient. A request must also come from a key on Gomry’s ACP partner allowlist and carry a valid request signature. A scope can be granted by anyone with settings access; a surface that can sell tickets and charge cards needs a gate a misconfigured dashboard cannot open. See Access.
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, applications:write, and spaces:write: legacy keys must be opted in explicitly so a key sitting in someone’s .env cannot silently start mutating tickets, ticket classes, applications, or — most sensitively — creating spaces and setting their tax details 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:
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.
