API keys and the public API

An API key is a password for a program, not a person. Use one when you want another system, such as a reporting spreadsheet or an accounting tool, to read or update your club's records without anyone signing in. If you want Claude or another AI assistant to help, do not use a key: connect it instead (see Connecting Claude to your club).

Only admins can create keys. Select API keys in the Club section of the admin navigation, beside Connect your AI. On a phone, open the navigation menu first. The link under Club → Staff & tools also remains available.

1. Give the key a Name that says what it is for, such as "board-reporting".

2. Tick the scopes it needs. A scope is one permission, such as invoices:read (look at invoices) or members:write (change member records). The areas are members, invoices, waitlist, relinquishments and camp, each with a :read and a :write scope, plus payables:read (look only). A write scope does not include the matching read scope: if a program needs to both read and change members, tick both. Give each key the smallest set it needs.

3. Select Create key. The key, which starts with opp_, is shown once. Copy it into the program or password manager that needs it. Swim Ops keeps only a fingerprint and cannot show it to you again. If you lose it, revoke it and make a new one.

The Existing keys table lists each key's name, the start of the key, its scopes and when it was last used. Revoke stops a key at once; anything using it stops working.

A key has no person or role behind it. It can do exactly what its scopes allow, for the whole club, from any computer, until it is revoked. So:

• Never paste a key into a chat or AI tool, an email or a shared document. Treat it like a password.

• Keys can't be created from a shared computer (signed in without Keep me signed in on this device). Sign in on your own device to create one. Revoking a key works from anywhere.

• Every admin of the club gets an email when a key is created. It names the key, what it can do and who created it, but never the key itself. If nobody expected the key, revoke it straight away.

• Review your keys now and then and revoke any that are no longer needed. If a key may be exposed, revoke it and create a replacement immediately.

The program sends the key with every request, in a header: Authorization: Bearer opp_…. Requests go to the club's web address under /api/v1.

• Writes need an Idempotency-Key. Any request that changes something must also send an Idempotency-Key header, a unique piece of text the program makes up, one per intended change. If the program has to retry (say a network error), sending the same key and the same request again replays a saved answer when one is available. If a change is refused while it runs, that answer is saved too: sending the same request again within ten minutes usually gets the same refusal, and after that it is tried again. The exception is a change the program has to confirm first (it asks for a preview, then sends the request again with the confirmation it was given). If the club refuses it at that last step, nothing is saved, so the program can ask for a fresh preview, confirm again, and have it tried straight away. A change that did go through is never done twice: confirming it again just returns the saved answer. If the result is still in progress or unknown, check the club record and contact support before making another attempt; do not switch to a new key to bypass that response. Support can clear it once the records are checked. Reusing a key for a different request is refused. Looking at things needs no such key.

• What a refusal and an error look like. When the club says no on purpose (a lane that is full, a week that is already taken, a period that is closed), the program gets a 400 error with the reason in plain words. If something unexpected goes wrong, it gets a 500 error with no detail. After a 500 on a change that had already started, treat the outcome as unknown: check the club record before trying again.

• Some actions can never be done with a key. Actions that need a person's approval on the website, such as sending a message to members, moving money, or changing settings, roles or how someone signs in, are refused for a key: it is told the action needs approval in the admin console. Those actions are available through a connected AI tool, where the person who asked approves each one.

• Accepting a waitlist offer is not in the API. A household accepts a membership or camp offer from the link in its offer email, or after signing in to the member portal when the club has turned that on. No key and no connected tool can accept an offer, because accepting creates an invoice in the member's name.

• Rate limit. A key may make 60 requests a minute. Past that, the program is told to wait and try again. Repeated attempts with a key that doesn't work are also slowed down.

The full list of actions, with who can use them, what each key scope covers and what each request looks like, is on the API docs page: select API docs at the top of the API keys page (admins only). It is generated from the same list that the admin screens and the connected AI tools use, so it is always up to date. Programmers can also read a machine-readable version at /api/v1/openapi.json on your club's web address.