Authentication

Most requests to the Gomry API must include a credential. The exception: an agent can browse events and build an order with no credential at all.

You are	Use	Reaches
An agent that finds a ticket and sends its buyer a page to pay on	Nothing. Send no `Authorization` or `X-API-KEY` header.	The catalog (`/catalog/*`) and checkout (`/checkout_sessions`), except paying with a token through `complete`
An agent that wants to browse events or buy tickets	A credential you register yourself. No human, no dashboard.	The catalog (`/catalog/*`) and checkout (`/checkout_sessions`)
An integration for one organization’s own data	An organization API key, created in the dashboard	That organization’s resources, per its scopes

For agents: no credential needed to quote

Create the checkout session with no credential and send your buyer its continue_url. They pay there by card, Apple Pay or Google Pay; nobody signs in to Gomry and nobody approves your agent. You need a credential only to pay yourself with a Shared Payment Token through complete, which otherwise answers 401 authentication_required. A credential that is sent and fails (wrong key, expired token, empty header, a key in the query string) always gets its 401. It is never treated as no credential.

For agents: get a credential yourself

You do not need an API key or a human to browse the catalog or buy tickets. Register once, then exchange your secret for a token whenever you need one. 1. Register (once). Send no redirect_uris. Save the client_secret: it is shown only once.

curl -X POST https://www.gomry.com/api/mcp/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My Agent", "grant_types": ["client_credentials"]}'

2. Get an access token. Tokens last 15 minutes and there is no refresh token: request a new one with the same secret.

curl -X POST https://www.gomry.com/api/mcp/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

3. Call the API with Authorization: Bearer:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://www.gomry.com/api/v1/catalog/events?starts_after=2026-10-12&starts_before=2026-10-18&city=New%20York"

The token response says scope: checkout:write. That is expected: catalog read access comes with it. Every endpoint outside the catalog and checkout answers 403, because this credential belongs to no organization. Full walkthrough, including payment: gomry.com/auth.md. Some agent platforms keep secrets away from the model, so they cannot send client_secret to the token endpoint. If a person can sign in, use the standard OAuth 2.1 authorization-code flow with PKCE instead and request checkout:write alongside mcp:

GET https://www.gomry.com/api/mcp/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_CALLBACK&code_challenge=...&code_challenge_method=S256
  &scope=mcp%20checkout%3Awrite&state=...

The consent page tells the person your agent can buy tickets for them. Their access token then works on the catalog and checkout as Authorization: Bearer, and the purchase is theirs: send no buyer and their verified name and email are used, and the tickets appear in their Gomry account. A token without the scope gets 403 insufficient_scope naming checkout:write; a token whose grant the person revoked stops buying at once (401). Full walkthrough: gomry.com/auth.md.

For integrations: organization API keys

Organization API keys are scoped to your organization and gated by a per-resource scope map that controls which resources the key can read or write. See Scopes for the full list and how to configure them.

Generating an API Key

Log in to your Gomry dashboard
Navigate to Organization Settings → API Keys
Click Create API Key and give it a descriptive name
Copy the key immediately — it is only displayed once

Treat your API key like a password. Anyone with your key can read your organization’s event data. Never commit it to version control or expose it in client-side code.

Using Your API Key

Include the key in the X-API-KEY header on every request:

curl -H "X-API-KEY: your_api_key_here" \
  https://www.gomry.com/api/v1/events/YOUR_EVENT_ID

const response = await fetch(
  "https://www.gomry.com/api/v1/events/YOUR_EVENT_ID",
  {
    headers: {
      "X-API-KEY": "your_api_key_here",
    },
  }
);
const { data } = await response.json();

import requests

response = requests.get(
    "https://www.gomry.com/api/v1/events/YOUR_EVENT_ID",
    headers={"X-API-KEY": "your_api_key_here"},
)
data = response.json()["data"]

Security Best Practices

Store keys in environment variables

Never hardcode API keys in your source code. Use environment variables or a secrets manager.

export GOMRY_API_KEY="your_api_key_here"

Use server-side requests only

API keys should only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or any code that runs on user devices.

Rotate keys periodically

Create a new key and revoke the old one periodically. You can manage keys in your dashboard under Organization Settings → API Keys.

Use separate keys for each integration

Create a dedicated key for each integration or service. This way, if a key is compromised, you can revoke it without affecting other integrations.

Authentication Errors

Status	Error	Meaning
`401`	`Missing API key. …`	No credential was sent to an endpoint that needs one. (The catalog and checkout accept no credential; see above.)
`401`	`authentication_required`	`complete` was called with no credential. Send the buyer the session’s `continue_url` instead
`401`	`Invalid or revoked API key`	The key doesn’t exist or has been revoked
`401`	`Access token invalid or expired …`	An agent token expired (they last 15 minutes). Request a new one with the same secret
`403`	`insufficient_scope`	The key is valid but lacks the required scope for this resource (see Scopes)

Getting Started

MCP Server

Agentic Commerce

Webhooks

Authentication

Authentication

For agents: no credential needed to quote

For agents: get a credential yourself

For integrations: organization API keys

Generating an API Key

Using Your API Key

Security Best Practices

Authentication Errors

​Authentication

​For agents: no credential needed to quote

​For agents: get a credential yourself

​Can’t send a client secret? Let the person sign in

​For integrations: organization API keys

​Generating an API Key

​Using Your API Key

​Security Best Practices

​Authentication Errors

Authentication

For agents: no credential needed to quote

For agents: get a credential yourself

Can’t send a client secret? Let the person sign in

For integrations: organization API keys

Generating an API Key

Using Your API Key

Security Best Practices

Authentication Errors