API keys and the public API

API keys (admin-only, at Club → Staff & tools → API keys) give an external tool programmatic access to this club's data over /api/v1, without sharing a login or a member's credentials. Use this when connecting a spreadsheet sync, a reporting tool, or any other integration a board member or vendor runs outside the platform.

1. Open Club → Staff & tools → API keys (or search with ⌘K).

2. Under Create a key, give it a Name that says what it's for (e.g. board-reporting): this is what you'll recognize later when deciding whether to revoke it.

3. Check the Scopes the integration actually needs. A key can only do what its scopes allow; a request for something out of scope is rejected.

4. Click Create key.

5. The plaintext key is shown once, in a banner: "Copy this key now, it will never be shown again." Copy it immediately into the integration's configuration. After you navigate away, the platform only ever has the key's hash: there is no way to retrieve the plaintext again, even for staff. If it's lost, revoke it and create a new one.

The key itself starts with opp_. Give it to the integration as a bearer token:

Authorization: Bearer opp_...

The full endpoint reference is linked from the API keys page as an OpenAPI spec (GET /api/v1/openapi.json).

Operations use GET or POST at /api/v1/ops/<name>. The API also provides its OpenAPI document and a run-status endpoint for asynchronous work. <name> is a dot-joined operation name (households.list, households.get, invoices.bulk_create, …); the OpenAPI document above lists every one this club's platform version exposes, grouped by domain, with its scope requirement and full request/response schema.

• Reads (an operation ending .list or .get) are GET, with the input as query parameters. E.g. GET /api/v1/ops/households.list?limit=25&query=smith.

• Writes are POST, with the input as a JSON body and a required Idempotency-Key header (see below). Some writes need a two-step confirmation: the response tells you so, with a preview and a token to send back on the next request.

A key's scopes gate which operations it can call the same way they always have: a request for an operation outside the key's scopes is rejected. Some operations (money and member-messaging writes. Issuing a waitlist offer, approving or denying a relinquishment, creating a camp registration, bulk-creating invoices) require staff approval in the admin console and are not reachable by any API key, regardless of scope — the response says so plainly rather than silently doing nothing.

On API keys, find the key in the Existing keys table and click the Revoke button. You'll be asked to confirm — revoking takes effect immediately and cannot be undone; a revoked key must be replaced with a newly created one, not restored.

Revoke and replace a key when:

• The integration or tool it was issued to is retired.

• You suspect the key leaked (pasted somewhere public, a vendor contact changed, a laptop was lost).

• You're switching to a different integration vendor for the same purpose.

The table also shows Last used, which updates on every successful authenticated request: a key that's shown "never" or a stale date is a reasonable one to question before an integration reports it's broken.

Creating and revoking keys is restricted to the admin role, the same access level as Club → Staff & tools. Other staff roles can't see or manage API keys.

Don't paste an API key into Claude or any chat tool. Use Connect instead. A key has no name on it and never expires. See Connecting Claude to your club for the right way to give an AI assistant access to this club.

Every write: POST /api/v1/ops/<name>: requires the calling tool to send its own Idempotency-Key header on each request. If a request's connection drops after it reached the server but before the response came back, retrying with the same Idempotency-Key will not create duplicate records: the platform recognizes the retry and returns the original result instead of re-running the write. Point whoever configures the integration at this requirement; without a stable idempotency key per logical write, a naive retry-on-timeout loop can double-submit data.

Pass this along to integrators in plain terms: generate one idempotency key per write attempt (not per retry. Reuse the same key across retries of the same attempt), and always retry with that same key rather than a fresh one. Three answers share the 409 status and mean different things:

• conflict: that key was already used with a different request body. Don't retry; something is wrong on the caller's side (a key reused across two logically different writes).

• in_progress: the first request with that key is still running. Retry shortly with the same key (the response carries Retry-After).

• stale_claim: the first request's execution was abandoned mid-flight and its outcome is unknown; the platform does not guess and re-run it. Inspect state (e.g. list the affected records) before retrying, and use a new Idempotency-Key for the retry. Reusing the same key keeps returning stale_claim.

"Can we get our data back out?": mostly yes, through several purpose-built exports rather than one big button. What exists today:

• Directory roster CSV. From Households, download the directory under its current filters, or export just the selected rows. Contact data only (household, address, members, email, phone, opt-ins, tags). money never appears in this export. It's capped at 5,000 households per file, and downloading it requires manager or admin. See Households and portal login.

• Camp roster CSV. Per camp week, including intake fields (allergies, pickup contacts), from the camp console.

• Treasurer CSVs: from Reports: receivables aging, bond liability, the monthly GL journal (QuickBooks-importable), the payouts reconciliation, and the approved check run. See Reports and CSV exports.

• Per-household statements. A printable statement per household (admin and member portal share the same view); members can print or email their own.

• The public API (/api/v1/ops/<name>): programmatic reads of households, memberships, invoices, payables, the membership waitlist, relinquishments, camp weeks, and every other domain the registry covers, scoped by API key as described above. For anything the CSVs don't cover, this is the general-purpose path.

Gaps today: there is no one-click full-account export today. Message history, tickets, workflow definitions and runs, the audit log, and signed agreements have no self-serve export. If a board needs those, pull what the API offers or ask Swim Ops support for a one-off extract.