Authentication and Scopes

Connecting an AI assistant to Swarmtix works the way "Sign in with Google" works. You are sent to a Swarmtix page, you see exactly what is being asked for, and you decide. Nothing is copied, pasted or stored by you.

Quick Start

1. Add https://swarmtix.com/mcp/v1 in your assistant
2. Your browser opens a Swarmtix page
3. Sign in, if you are not already signed in
4. Choose the organisation this connection is for
5. Read the permission list — it is written in plain English, not scope names
6. Click Allow, or Deny if it is asking for more than you want to give

Your assistant is now connected. To undo it later, go to Settings → Developers → Connections and revoke it.

There Is No API Key

This is the first thing people look for, so it is worth being direct: the MCP server has no API key, token or secret for you to generate.

The reason is that a key is a bearer credential. Anyone who gets a copy of it is you, for as long as it exists, with every permission it carries. OAuth replaces that with a credential that is issued to one named client, limited to the permissions you approved, bound to one organisation, and revocable from your settings page in one click.

What the Consent Page Shows You

Before you approve anything, the page tells you four things:

1. Which client is asking. The name the client registered — "Claude", "ChatGPT", your own app.
2. Which organisation is being granted. If your account belongs to several, this is where you pick.
3. What it will be able to see or change, one line per permission, written for people rather than for developers.
4. Allow and Deny, and Deny is a real option. Nothing happens until you click Allow.

The Nine Scopes

A scope is a permission. Your assistant asks for a set of them, you approve or refuse the whole set, and everything it can do afterwards is bounded by what you approved.

Barcodes are never returned

No scope exposes a ticket's barcode or security code, and no tool returns one. Those codes are the credential that admits someone to your event — a copy of a barcode is a free ticket. They are stripped before a tool result is built, whatever permissions the connection holds.

So an assistant with orders:read and attendees:read can tell you that Sarah bought two tickets and what her email address is. It cannot produce anything that would get her, or anyone she forwards it to, through the door.

What none of them allow

No scope, in any combination, permits a refund, a charge, publishing or unpublishing an event, a check-in, a bulk email to attendees, a guest-list import, a deletion of any kind, an account or subscription change, or registering a webhook. Those are not permissions that were left switched off — no tool exists for them.

Editing an existing event's own record is in the same position for a different reason: it is not a permission you can grant, because there is no tool for it. events:write builds a draft and fills in its schedule, tickets, questions and discounts; the event's name, description, venue, host and branding are edited in the dashboard.

Scopes hide tools, not just block them

If you do not approve discounts:write, the assistant does not see a tool for creating discounts at all. It is filtered out of the tool list rather than failing when called.

That matters in practice: an assistant that cannot see a capability will not suggest it, will not try it, and will not tell you it is "having trouble" with it. Approving less genuinely gives you a smaller assistant.

One Connection, One Organisation

The organisation is fixed at the moment you approve the connection and is carried inside the token itself. No tool takes an organisation as a parameter, so nothing the assistant reads — a document, a web page, an instruction in a message — can redirect it at someone else's data.

If you belong to two organisations and want the assistant to reach both, connect twice. Most clients let you add the same server under two names.

How Long Access Lasts

Your client handles both without being asked. In practice a connection you use regularly keeps working indefinitely, and one you leave untouched for 30 days asks you to sign in again.

Refresh tokens rotate: each one can be used exactly once, and using it produces a replacement. If a consumed refresh token is presented again — which is what a stolen copy looks like — the entire grant is revoked, not just that token. You reconnect; whoever took it gets nothing.

Revoking takes effect immediately

When you click Revoke, the connection is dead on the next call. Not in an hour, not when something expires.

That is a deliberate engineering choice rather than a given. Most OAuth servers issue self-contained tokens that carry their own permissions and are trusted until their expiry passes, which means a revoked token keeps working for as long as it had left — up to an hour here. A settings page that says "revoked" while the agent carries on reading orders is a lie.

Swarmtix issues reference tokens instead. The token is a handle, checked against the server's own store on every single call, so removing the grant stops the very next request. It costs a lookup per call. On a connector that reads your customers' data, being able to actually cut it off is worth more.

Reviewing and Revoking a Connection

Everything lives under Settings → Developers, next to Webhooks in the settings sidebar.

Connections

Every assistant you have authorized, which organisation it was granted, which scopes it holds, and when. Each one has a Revoke action.

Revoking ends the connection at once. Any access token it is holding stops working on its next call, its refresh token is dead, and it has to be authorized again from scratch — approving the consent page a second time — before it can do anything.

Credentials

One list covering all three kinds of credential: OAuth clients authorized by your organisation, MCP connections, and the older 90-day API tokens. One place to look, one revoke action.

Logs

One row per call, for both the MCP server and the REST API: when, which credential, which tool or endpoint, whether it succeeded, how long it took, the client's IP and user agent.

Request and response bodies are not stored. They contain attendee personal data, and a log table is the wrong place for it.

Usage

Call volume, error rate, response times and your most-used tools, over the same time-period filter as the rest of your analytics.

For Developers: How the Flow Works

Swarmtix runs a full OAuth 2.1 authorization server. If you are building your own client, these are the details that matter.

Properties worth knowing before you build against it:

• PKCE with S256 is required. An authorization request without a code challenge is refused. There is no exception for confidential clients.
• Tokens are audience-bound. Pass the RFC 8707 resource parameter; it is echoed into aud, and the server checks it on every call. A token minted for another resource is rejected.
• The authorization response carries iss (RFC 9207), so you can verify which server answered.
• Signing is asymmetric (RS256), verifiable against the published JWKS.
• Access tokens are reference tokens, not self-contained JWTs. Do not try to decode one for its claims — it is an opaque handle, validated server-side on every call. Use /connect/userinfo for identity. This is what makes revocation immediate.
• Handle rotation properly. Refresh tokens are single-use. Store the replacement you get back; presenting a consumed one revokes the whole grant chain.
• Client registration works two ways — Dynamic Client Registration (RFC 7591), and Client ID Metadata Documents. DCR is deprecated in the newest protocol revision but is what most deployed clients still use, so both are supported.
• Consent must be top-level. X-Frame-Options: SAMEORIGIN is set, so the consent page cannot be embedded.
• Your token is never forwarded upstream. Swarmtix does not pass your access token to any third-party API on your behalf.

Troubleshooting

"This connection is not authorized for events:write. Reconnect and grant it to use this tool."

The tool needs a permission this connection does not hold. The message names the exact scope — events:write in this example, but it can be any of the nine. Revoke the connection, authorize it again, and approve that permission on the consent page. The tool reference lists the scope each tool requires.

The assistant says a tool does not exist, with no error message at all

Same cause, no message. Tools outside your approved scopes are removed from the list rather than refused when called, so the assistant genuinely cannot see them and has nothing to report. If a capability seems to be missing entirely, check its scope in the tool reference and re-authorize with that permission approved.

401 on every call, right after it was working

Either the connection was revoked — by you, or by a colleague from the same settings page, in which case it stopped the moment they clicked — or the refresh token has passed its 30 days. Reconnect from your client's settings. Access tokens last an hour and your client renews them on its own, so ordinary expiry is not usually the cause.

The consent page says the organisation is wrong

The organisation is chosen at approval time and cannot be changed afterwards. Revoke the connection and authorize a new one against the right organisation.

The consent page never appears

Your client is trying to embed it. Swarmtix refuses to be framed. Use a client that opens your system browser for sign-in.

"Event not found, or this connection does not have access to it."

One message, three causes: the event does not exist, it belongs to a different organisation than the one this connection was granted, or it belongs to a team inside your organisation that the authorizing organizer is not a member of.

That is on purpose. A separate "you do not have permission" error would confirm the event exists, which is itself a fact about someone else's organisation. The cases are deliberately indistinguishable, so nothing about another organisation's data can be inferred from the wording.

If you can see the event in your own dashboard, check which organisation the connection covers, in Settings → Developers → Connections, and which account authorized it — a connection reaches only the events that account created or is on the team for.

"Swarmtix could not complete this request. Nothing was changed."

Something failed on our side. The important half of that sentence is the second one — the request did not partly apply, so retrying it cannot produce a duplicate of whatever it was doing. If it keeps happening, contact support with the time it occurred so the call can be found in Settings → Developers → Logs.

"Swarmtix applied part of this request and then stopped…"

The opposite promise, and the reason the closing phrase above is worth reading. One tool — swarmtix_event_dates_set — can get part way through and stop, and when it does it says what landed and what did not rather than implying a clean slate. Check the current state before calling it again.