Activities Server API Reference

The activities server is the backend behind Carrier Wave: Field (iOS), CW Sweep (macOS), Carrier Wave for Android, and the logbook web viewer. One service exposes everything described on this page:

• a versioned JSON API under /v1
• an OAuth 2.0 / OpenID Connect provider so other apps can act for a user
• an end-to-end encrypted sync journal for the user’s log
• server-rendered share and invite pages
• public reference data: spots, Reverse Beacon Network, POTA statistics, park boundaries, historic trails, satellite status, contest definitions, radio macros, an equipment catalog

This page is the complete wire-level reference. For how the features behave inside the apps, see the Reference Manual .

Who this is for. Anyone can read the public endpoints. The authenticated social endpoints (challenges, friends, clubs, events, feed) are first-party only: they accept Carrier Wave’s own app tokens and reject third-party OAuth tokens. Third-party developers get the user’s identity and the sync journal. If you need more, write to hello@carrierwave.app .

Reading this with a tool or an agent? This page is also served as plain Markdown at https://carrierwave.app/manual/developers/api/index.md , and https://carrierwave.app/llms.txt lists everything machine-readable. The short version with ready-to-run requests is Using the API from agents and tools .

Hosts and versioning

All JSON API routes are nested under /v1. There is no /v2: changes are made additively because shipped app builds keep calling old shapes for a long time. Fields may be added to responses at any time; clients must ignore unknown fields.

A few routes live at the domain root because external software expects them at conventional paths:

• /.well-known/openid-configuration and /.well-known/oauth-authorization-server (OAuth discovery)
• /.well-known/jwks.json (token verification keys)
• /.well-known/apple-app-site-association (iOS universal links)
• /invite/:token and /link/... (HTML landing pages for shared URLs)
• /metrics (Prometheus exposition)

Unknown paths under /v1 return a JSON 404 (see Error format ).

Conventions

• JSON everywhere unless an endpoint says otherwise. Request and response bodies use camelCase field names. The exceptions are the OAuth token endpoints, which follow the RFC 6749 snake_case wire format and accept form-encoded bodies, and the Twilio webhook.
• Identifiers are UUIDs unless the resource has a natural key: program slug, macro slug, park reference, contest id, callsign.
• Timestamps are RFC 3339 in UTC with a Z suffix.
• Callsigns are normalised to upper case by the server. Path parameters that take a callsign accept any case.
• Response envelopes. The original challenge-era endpoints wrap their payload in {"data": ...}. Endpoints added later return the object or array directly. Each endpoint below shows its exact shape; do not assume.
• Pagination is offset-based (limit and offset query parameters) on list endpoints that paginate. The activity feed uses a cursor. Limits and maxima are listed per endpoint.
• Request ids. Every response carries X-Request-Id. Send your own and it is echoed back; otherwise one is generated. Quote it when reporting a problem.
• Conditional requests. Several reference-data endpoints emit an ETag and honour If-None-Match with 304 Not Modified. They are called out individually. Use them: the datasets are large and change slowly.

Authentication

Credentials are sent as Authorization: Bearer <token>. Five situations exist:

How routes treat a bearer:

• Public routes accept an optional bearer. A valid one personalises the response (for example a leaderboard’s userPosition). An invalid, expired, revoked or out-of-scope token is silently ignored and the request proceeds anonymously, so public routes never return 401.
• First-party routes require a bearer. Missing or invalid gives 401 INVALID_TOKEN. A third-party token outside its allowed set gives 403 FORBIDDEN.
• Account-management routes under /v1/auth/ accept only account tokens, never fd_ device tokens.
• Admin routes compare the bearer to the operator secret.

Some first-party routes also require that the caller has an account (an email-verified identity) and not merely a device token. Those answer 403 ACCOUNT_REQUIRED; the sync journal is the main example.

The sign-in flows are described in full under Authentication and accounts and OAuth 2.0 / OpenID Connect provider .

Third-party access

A token minted for a registered OAuth client is default-denied: it is refused on every route not in this table, regardless of scope. The absence of an entry is itself the policy.

The scopes a client may request, with the wording the user sees on the consent screen:

Unknown scope strings are dropped from the request rather than rejected.

Rate limits, CORS and body size

When a limit trips the response is not the JSON error shape. It is 429 Too Many Requests with a plain-text body Too Many Requests! Wait for <n>s and an x-ratelimit-after: <n> header. No X-RateLimit-Limit or X-RateLimit-Remaining headers are sent. The limits are enforced inside the application on the aggregate traffic that reaches it, so treat them as a ceiling, not a per-client allowance, and back off on 429.

CORS allows the origins https://carrierwave.app and https://activities.carrierwave.app, the methods GET POST PUT DELETE OPTIONS, and the headers Authorization and Content-Type. Browser-based third-party apps therefore cannot call the API directly from another origin; use a backend. Native and CLI clients are unaffected.

Request bodies are capped at 1 MiB. Upload endpoints that need more (badge images, club logos, sync pushes and snapshots) say so in their notes. Oversized bodies are rejected before the handler runs, as 400 VALIDATION_ERROR on most endpoints.

Error format

Application errors are JSON:

{
  "error": {
    "code": "CHALLENGE_NOT_FOUND",
    "message": "Challenge not found",
    "details": { "challengeId": "7d6c…" }
  }
}

• code is a stable upper-snake identifier. Branch on it, never on message.
• message is human-readable and may change.
• details is omitted when there is nothing to add.

Unknown /v1 paths return 404 with code NOT_FOUND. Malformed JSON, a body that fails validation, or an unparseable path parameter is 400 VALIDATION_ERROR with the parser’s explanation as the message. A few older handlers answer those cases with a plain-text 400 or 422 instead. 304 Not Modified has no body.

The OAuth token, device-code and revoke endpoints use the RFC 6749 error shape ({"error": "invalid_grant", "error_description": "…"}).

The complete list of application error codes is in Appendix: error codes .

Endpoint index

Every route the server mounts. “Auth” is the gate the route sits behind; individual handlers may add further checks such as ownership, account required, or scope.

Routes marked Admin token are operated by Carrier Wave staff through the admin console. They are listed for completeness and summarised briefly in each section; their request and response shapes are not documented here.

Authentication and accounts

All paths are under /v1 unless noted. Carrier Wave uses two kinds of credential.

Device tokens. The original scheme. A device token is an opaque string with the fd_ prefix, issued by POST /v1/register on the first registration of a callsign (and by challenge join). It carries no account identity and cannot be recovered if lost.

Account tokens. A Carrier Wave account owns one or more verified callsigns and issues two tokens per device:

• Access tokens are JWTs signed with EdDSA (Ed25519). They live for 15 minutes; the server allows 60 seconds of clock skew. The header kid names the signing key published at /.well-known/jwks.json. Claims:
  • iss: always https://activities.carrierwave.app
  • sub: the account id (UUID)
  • aud: cw-social (accepted by this API) or cw-sync (accepted only by the sync service). A token minted for one audience is rejected by the other.
  • scope: space-delimited scopes from the set sync:read sync:write social:read social:write account. If you request no scopes or only unknown ones, you receive the full set.
  • cs: the account’s primary callsign. Informational only; the server never uses it for authorization and re-resolves the acting callsign from the account.
  • iat, exp: unix seconds
  • jti: random UUID
  • cid: present only on tokens issued to third-party OAuth clients. Tokens issued by the endpoints in this section never carry it. Third-party tokens are refused (403 FORBIDDEN) by every endpoint in this section and treated as anonymous by the public ones.
• Refresh tokens are opaque strings with the cwr_ prefix. Each has a sliding lifetime of 60 days, and the family it belongs to has an absolute lifetime of 180 days, after which you must verify by email again. Every refresh rotates the token. Re-presenting the previous token within a 60 second grace window returns the current live pair; outside that window the server treats it as reuse and revokes the whole family. One refresh family corresponds to one device.

Email verification flow. Sign-in and onboarding use a magic link plus PKCE.

1. Generate a PKCE verifier and compute pkceChallenge = hex(sha256(verifier)), 64 hex characters (not base64url). Call POST /v1/auth/verify/start with the callsign and optionally a fallback email. If the amateur radio directory has an email for that exact callsign, the link goes there; otherwise it goes to the email you supplied. If the callsign already belongs to an account, the link goes only to that account’s on-file address and your email is ignored. The response is always 202 with a pollToken, whether or not any mail could be sent.
2. The email contains a link to GET /v1/auth/verify/complete?code=<code>. Opening it marks the verification as clicked (single use) and shows a static page. The code alone is not a credential.
3. Finish one of two ways. If your app received the code (for example through a universal link), call POST /v1/auth/token with code and pkceVerifier. Otherwise poll POST /v1/auth/verify/poll with pollToken and pkceVerifier; 202 means not clicked yet, any other status is the same result /auth/token would return. Both paths consume the verification.
4. The outcome depends on what was started. Onboarding (unclaimed callsign): a new account, device and tokens, 201. Sign-in (callsign already owned): a new device on that account, 201. Attach (started from /auth/callsigns/verify/start by a signed-in account): the callsign is added to the account and no tokens are issued, 204.

Verifications expire 15 minutes after they are started.

Device management. Every token issuance creates a device (deviceName, platform) with its own refresh family. GET /auth/devices lists devices, DELETE /auth/devices/:id revokes one, POST /auth/logout revokes the family of a given refresh token, and POST /auth/logout/all revokes everything.

Revocation. Access tokens are verified without a database lookup, so revocation has two strengths. POST /auth/logout/all and PUT /account/callsign invalidate every existing access token for the account immediately, including the one used to make the call. POST /auth/logout and DELETE /auth/devices/:id revoke only the refresh family: an access token already issued for that device stays valid until it expires, at most 15 minutes later.

Which bearer an endpoint accepts.

• Public: no credential needed. A bearer, if sent, is ignored.
• Bearer (first-party): a device token or a first-party account access token. An account token acts as the account’s primary callsign.
• Account token: an account access token only, with the account scope. A device token is rejected with 401 INVALID_TOKEN; a token without the scope is rejected with 403 FORBIDDEN.

ACCOUNT_REQUIRED. Some features outside this section (sync, OAuth user info and grants) need an account-backed session. When you call them with a device token you receive 403 with code ACCOUNT_REQUIRED and a message saying that a Carrier Wave account is required. Sign in with the email flow above to continue.

The /v1/auth/* and /.well-known/* endpoints exist only when account sign-in is enabled on the server; otherwise they return 404 and only device tokens are accepted.

Sign-in and tokens

Start callsign verification

POST /v1/auth/verify/start

Auth: Public Rate limit: 1 request per 20 s per IP, burst 3, in addition to the global limit.

Request

{
  "callsign": "W6JY",
  "email": "me@example.com",
  "pkceChallenge": "3f1a…64 hex chars…"
}

Response 202 Accepted

{ "pollToken": "cwp_<64 hex>" }

Always 202 with a fresh poll token, even if no email was sent (unknown callsign with no deliverable address, account with no stored email, delivery failure). You cannot tell from the response whether mail went out.

Errors

Notes

• If the callsign already belongs to an account, the link goes to the directory email if one resolves, else the account’s stored verified email. Your email is ignored.
• The emailed link is https://activities.carrierwave.app/v1/auth/verify/complete?code=<32 hex>.

Magic-link landing page

GET /v1/auth/verify/complete?code=<code>

Auth: Public

Response 200 OK, Content-Type: text/html. A self-contained Carrier Wave page saying either “Callsign verified” (return to the app to finish signing in) or “Link expired” (invalid or expired). Status is 200 in both cases. Headers: referrer-policy: no-referrer, content-security-policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:, cache-control: no-store.

Errors

Notes

• Single use: a second visit shows the “expired” page.
• Opening the link does not issue tokens. The app must still present the PKCE verifier to /auth/token or /auth/verify/poll.

Poll for verification completion

POST /v1/auth/verify/poll

Auth: Public

Request

{
  "pollToken": "cwp_<64 hex>",
  "pkceVerifier": "the-verifier-whose-sha256-hex-was-sent",
  "deviceName": "Jay's iPhone",
  "platform": "ios",
  "scopes": "sync:read sync:write social:read social:write account"
}

Response, one of:

• 202 Accepted, empty body: link not yet clicked, poll token unknown, or verification expired. The server does not distinguish these, so stop polling after 15 minutes.
• 201 Created, onboarding or new-device sign-in:

  {
    "access": "<EdDSA JWT>",
    "refresh": "cwr_<64 hex>",
    "expiresIn": 900,
    "accountId": "4c4a1b3e-…"
  }
  

• 204 No Content: the verification was an attach (started via /auth/callsigns/verify/start). The callsign is now on the account; no new tokens.

Errors

Notes

• Tokens are identical to those from /auth/token. The access token audience is always cw-social.
• On 201 a new device and refresh family are created; on onboarding the account is created too.

Exchange a clicked verification code for tokens

POST /v1/auth/token

Auth: Public

Request

{
  "code": "<32 hex from the emailed link>",
  "pkceVerifier": "…",
  "deviceName": "Jay's iPhone",
  "platform": "ios",
  "scopes": "sync:read sync:write"
}

code and pkceVerifier are required. The optional fields and their defaults are the same as /auth/verify/poll.

Response: 201 Created with access, refresh, expiresIn (900) and accountId, or 204 No Content for the attach case. Same semantics as /auth/verify/poll.

Errors

Notes

• The link must have been opened first. A successful exchange consumes the code.
• Not to be confused with POST /v1/oauth/token, the third-party OAuth token endpoint.

Refresh (rotate) tokens

POST /v1/auth/token/refresh

Auth: Public (the refresh token in the body is the credential)

Request

{ "refresh": "cwr_<64 hex>", "aud": "cw-social" }

Response 200 OK

{ "access": "<JWT>", "refresh": "cwr_<new 64 hex>", "expiresIn": 900 }

Errors

Notes

• Rotation is serialized per family. A concurrent or retried refresh with the previous token inside the grace window returns a fresh pair rather than revoking, so an app, widget and watch sharing one device do not lock each other out.
• Scopes carry over from the refresh token. cs is re-read from the account’s primary callsign at mint time.

Log out this device

POST /v1/auth/logout

Auth: Public (refresh token in body)

Request

{ "refresh": "cwr_<64 hex>" }

Response: 204 No Content. Idempotent: an unknown token also returns 204.

Errors

Notes

• Revokes every token in the refresh family. The device entry is not removed from GET /auth/devices, and an outstanding access token for the device remains valid until it expires (at most 15 minutes).
• Works with any token in the family, including an already-rotated one.

Account management

These endpoints require an account access token with aud cw-social, a valid signature, unexpired, not revoked, and carrying the account scope. Checks run in that order: a missing, invalid, expired or revoked bearer is 401 INVALID_TOKEN; a third-party token or a missing account scope is 403 FORBIDDEN. A device token is rejected with 401 INVALID_TOKEN.

Log out everywhere

POST /v1/auth/logout/all

Auth: Account token

No params, no body.

Response: 204 No Content.

Errors

Notes

• Revokes every refresh token for the account and immediately invalidates every access token issued before the call, including the one used to make it. Device entries are not deleted, so a fresh session still sees them in GET /auth/devices.

List devices

GET /v1/auth/devices

Auth: Account token

Response 200 OK

{
  "data": [
    {
      "id": "0e7c…",
      "deviceName": "Jay's iPhone",
      "platform": "ios",
      "createdAt": "2026-10-01T18:04:11.120Z",
      "lastSeenAt": "2026-10-01T18:04:11.120Z"
    }
  ]
}

Ordered by lastSeenAt descending. deviceName and platform are null when not supplied at token issuance. At present lastSeenAt is set when the device is created and not updated afterwards, so it matches createdAt.

Errors: 401 INVALID_TOKEN, 403 FORBIDDEN as above.

Notes: Devices whose refresh family was revoked via /auth/logout or /auth/logout/all still appear. Only DELETE /auth/devices/:id removes an entry.

Revoke a device

DELETE /v1/auth/devices/:id

Auth: Account token

Response: 204 No Content. Idempotent: 204 even if the device does not exist or belongs to another account.

Errors

Notes: Revokes that device’s refresh tokens and removes the device entry. The device’s current access token lives on until expiry.

Start verification of an additional callsign

POST /v1/auth/callsigns/verify/start

Auth: Account token Rate limit: none route-specific (only the global limit), unlike the public /auth/verify/start.

Request: same body as /auth/verify/start: callsign (required), email (optional fallback), pkceChallenge (required, 64 hex).

Response: 202 Accepted { "pollToken": "cwp_…" }.

Errors: VALIDATION_ERROR 400, INVALID_TOKEN 401, FORBIDDEN 403 (scope), INTERNAL_ERROR 500.

Notes

• The verification is bound to your account. Ownership by another account is not checked at this stage; the directory-else-supplied email is used. On completion via /auth/token or /auth/verify/poll: if your account already owns the callsign, the completion behaves like a sign-in (new device and tokens, 201); otherwise the callsign is attached and you receive 204, or 409 CALLSIGN_TAKEN if another account holds it.
• Attaching a callsign does not change the account’s primary callsign. Use PUT /account/callsign for that.

Key discovery

JSON Web Key Set

GET /.well-known/jwks.json

Auth: Public. Served at the domain root, not under /v1.

Response 200 OK, headers content-type: application/json, cache-control: public, max-age=3600:

{
  "keys": [
    { "kty": "OKP", "crv": "Ed25519", "use": "sig", "alg": "EdDSA", "kid": "v1", "x": "<base64url raw 32-byte public key>" }
  ]
}

The set contains exactly one key, the current signing key. After a key rotation, tokens signed with the previous key no longer verify.

Errors: none specific (404 when account sign-in is disabled).

Notes: The same location also serves /.well-known/openid-configuration and /.well-known/oauth-authorization-server for the third-party OAuth provider, documented separately.

Legacy registration and user search

Both endpoints are public. A bearer, if present and valid, is accepted but has no effect on the response; an invalid bearer is ignored, not rejected.

Register a callsign (legacy device token)

POST /v1/register

Auth: Public (optional bearer; no effect) Rate limit: 1 request per 60 s per IP, burst 1.

Request

{ "callsign": "w6jy ", "deviceName": "Jay's iPhone" }

Response 201 Created

{ "data": { "userId": "b1a2…", "deviceToken": "fd_<32 alnum>" } }

deviceToken is omitted entirely when the callsign is already registered. Re-registering an existing callsign never yields a credential. userId (the friend-search identity) is returned in both cases. Status is 201 even when nothing new was created.

Errors

Notes

• Callsign ownership is not verified here; anyone can register any unclaimed callsign.
• A lost device token cannot be reissued. Recover access through the email verification flow.

Search users by callsign

GET /v1/users/search?q=<fragment>

Auth: Public (optional bearer; no effect)

Response 200 OK

{ "data": [ { "userId": "b1a2…", "callsign": "W6JY", "displayName": null } ] }

Up to 20 rows, ordered by callsign. displayName is currently always null.

Errors

Notes: The length check on q counts bytes, not characters. % and _ in q act as SQL wildcards.

Account changes

These endpoints accept a device token or a first-party account access token. A missing or invalid bearer is 401 INVALID_TOKEN; a third-party token is 403 FORBIDDEN. An account token acts as the account’s primary callsign.

Delete account

DELETE /v1/account

Auth: Bearer (first-party)

No params, no body.

Response: 204 No Content.

Errors

Notes

• Deletes the callsign’s profile and everything keyed to it: challenge participation, progress, badges, friendships, friend requests, friend invites and activities. Any device tokens for the callsign stop working.
• For account-backed callers this does not delete the account, its verified callsigns, its devices or its tokens, and the session remains valid.

Change callsign

PUT /v1/account/callsign

Auth: Bearer (first-party)

Request

{ "newCallsign": "W6JY" }

newCallsign is required; trimmed and upper-cased. No explicit length cap (unlike /register).

Response 200 OK

{ "data": { "callsign": "W6JY" } }

Errors

Notes

• Renames the callsign everywhere it appears (profile, challenges, progress, badges, activities, club membership, spots) and records the change in the callsign history.
• For account callers who own the current callsign, the account’s verified callsign and primary callsign are rewritten and every existing access token is invalidated immediately, including the one used for this call. Call /auth/token/refresh to obtain a token whose cs reflects the new callsign. Refresh tokens are not revoked.

Claim a previous callsign’s data

POST /v1/account/claim-previous

Auth: Bearer (first-party), effectively account tokens only. A device token authenticates but is refused with 403 FORBIDDEN (not ACCOUNT_REQUIRED).

Request

{ "previousCallsign": "KN6ABC" }

previousCallsign is required; trimmed and upper-cased.

Response 200 OK

{ "data": { "merged": true, "previousCallsign": "KN6ABC" } }

Errors

Notes

• Prerequisite: verify the old callsign on the same account first via POST /auth/callsigns/verify/start, the emailed link, then /auth/token or /auth/verify/poll (204 attach).
• Merges the old callsign’s friendships (both directions, skipping duplicates), friend requests and activities into the current callsign, and moves its challenge participation, progress, badges, club membership and spots. The old profile is then deleted, which invalidates any device tokens for the old callsign.
• The old callsign stays attached to the account.

OAuth 2.0 / OpenID Connect provider

Carrier Wave is an OAuth 2.0 authorization server and an OpenID Connect provider. Your application can sign a Carrier Wave user in and, with the user’s consent, read and write their encrypted log through the /v1/sync/* endpoints. The user signs in on Carrier Wave’s own pages, so your app never handles their credentials. This is separate from the magic-link sign-in that Carrier Wave’s own apps use.

All endpoints below are served from https://activities.carrierwave.app. The /.well-known/* documents live at the domain root; every other path is under /v1. On a server where OAuth is not enabled, the discovery documents and the public /v1/oauth/* endpoints return 404.

Registering a client

Client registration is curated. There is no self-serve portal and no dynamic client registration (RFC 7591). Email hello@carrierwave.app to register a client and include:

• The client id you would like (a short identifier such as my-logger) and the name users should see on the consent screen. A description and a homepage URL are optional; the homepage is shown on the consent screen as “Developer site”.
• Your redirect URIs, if you use the authorization code flow. They are matched exactly: no wildcards, no prefixes, no normalization. Loopback URIs such as http://127.0.0.1:<port>/callback are fine for CLIs.
• The scopes you need. This becomes your client’s ceiling; see Scopes and consent below.
• The grant types you need. Authorization code and refresh token are the default. Ask for device_code if you need the device flow.
• Whether the client is confidential (a server that can keep a secret) or public (native app, SPA, CLI).

A confidential client receives a secret of the form cws_ followed by 40 alphanumeric characters. It is shown once and cannot be retrieved again. A public client has no secret, must not send one, and relies on PKCE instead.

Carrier Wave staff can suspend a client. A suspended client behaves exactly like an unknown one (invalid_client), so the two are indistinguishable to callers. There is no update endpoint; contact Carrier Wave to change redirect URIs or scopes.

Grant types

Not supported: implicit (response_type=token), client credentials, dynamic registration (RFC 7591), token introspection (RFC 7662). response_types_supported is ["code"] only. Each client may use only the grant types it was registered with; any other grant returns unsupported_grant_type.

Scopes and consent

These are the only scopes that exist. Any other scope string is silently dropped from a request, so an unknown scope can never become an authorization. The consent screen shows exactly this text next to each scope:

Scope rules:

• If a request omits scope, the server uses openid.
• Requested scopes are filtered to the known set, then clamped to your client’s registered ceiling, preserving request order and dropping duplicates. You can always ask for less, never more.
• openid in the granted set turns the authorization into an OpenID Connect login and an id_token is minted. email additionally puts the verified email into the ID token and UserInfo.
• profile currently has no effect beyond appearing on the consent screen and in the token’s scope claim. callsign and preferred_username are always returned by UserInfo.
• Whenever any sync:* scope is requested, the consent screen shows an explicit warning about the sync passphrase.

What a third-party token may call

Access tokens issued to your client carry a cid claim (your client id). Every request made with such a token is checked against the table below. The route must be listed and the token must carry the exact scope shown (no prefix or wildcard matching; the HTTP method is part of the check). Anything else returns 403 FORBIDDEN. Everything not listed, including clubs, friends, spots, events, contests, account management, the first-party /v1/auth/* routes and the OAuth flow routes themselves, is reserved for Carrier Wave’s own apps.

The /v1/sync/* endpoints are documented separately. A refresh token issued by the OAuth provider cannot be used at the first-party POST /v1/auth/token/refresh; that returns 403 FORBIDDEN without rotating the token. Use POST /v1/oauth/token with grant_type=refresh_token.

Reading and writing the encrypted log

The log is an append-only journal of encrypted blobs. A token authorizes access to ciphertext, never decryption. The data key is derived on the user’s device from their sync passphrase with Argon2id and never reaches the server.

1. GET /v1/sync/key (sync:read) returns the passphrase-wrapped data-key envelope. 404 means the user has not set up sync.
2. Ask the user for their sync passphrase in your own UI. Derive a key-encryption key with Argon2id and use it to unwrap the 32-byte data key.
3. GET /v1/sync/bootstrap for a first sync, or GET /v1/sync/changes?since=<n> for an incremental one. Each entry has a monotonic seq and a presigned download URL.
4. For each entry: download, decrypt with ChaCha20-Poly1305 using the data key, gunzip, and parse the journal payload JSON.
5. Fold payloads in seq order. Payloads are upserts and delete tombstones; the last write by seq wins. Persist the highest seq you have seen.
6. To write: build the QSO record or tombstone, wrap it in a journal payload, gzip it, seal it with the same key, call POST /v1/sync/push (sync:write) to get a presigned upload URL per entry, then PUT the ciphertext there. Push is idempotent on client_entry_id.

Wire details to watch: frequency is in MHz; field names are camelCase, with rawADIF and isActivityLogQSO as irregular spellings; entries are never modified in place.

Error bodies

Two shapes appear in this family:

• RFC 6749 section 5.2 bodies on the OAuth protocol endpoints and the decision endpoints: {"error": "<code>", "error_description": "<text>"}, sent with Cache-Control: no-store and Pragma: no-cache. Status by code: invalid_request 400, invalid_client 401, invalid_grant 400, unsupported_grant_type 400, invalid_scope 400, access_denied 403, authorization_pending 400, slow_down 400, expired_token 400. The 401 invalid_client response does not set a WWW-Authenticate header.
• The server envelope on UserInfo, connected-app routes, and for any bearer rejection: {"error": {"code": "<CODE>", "message": "<text>"}}, with an optional details field. Codes you may see: INVALID_TOKEN 401, ACCOUNT_REQUIRED 403, FORBIDDEN 403, VALIDATION_ERROR 400, RATE_LIMITED 429, INTERNAL_ERROR 500.

A request with the wrong content type, an unparseable body, or a missing required field such as grant_type is rejected before the OAuth handler runs and returns a plain-text error rather than an RFC 6749 body.

Every route is rate limited at roughly 10 requests per second with a burst of 20; beyond that you receive 429. Request bodies are capped at 1 MiB.

Walkthrough: authorization code flow (apps with a redirect)

1. Generate a random code_verifier (43 to 128 characters) and a random state. Compute code_challenge = base64url_nopad(sha256(code_verifier)). Optionally generate a nonce.

2. Send the user’s browser to the consent page:

   GET /v1/oauth/authorize?client_id=my-logger
     &redirect_uri=https%3A%2F%2Fmylogger.example%2Foauth%2Fcallback
     &response_type=code
     &scope=openid%20sync%3Aread%20sync%3Awrite
     &state=5f1c…
     &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
     &code_challenge_method=S256
     &nonce=n-0S6_WzA2Mj
   

   The page is self-contained HTML. The user signs in on that page with a Carrier Wave magic link, so your app never sees their credentials, then clicks Allow or Deny. The page records the decision and sends the browser to your redirect URI.

3. The browser lands on your redirect_uri:

   • success: ?code=<48-character code>&state=5f1c…
   • refusal: ?error=access_denied&state=5f1c…
   • malformed request: ?error=unsupported_response_type|invalid_request|invalid_scope&state=…

   Verify that state matches what you sent. An unknown client_id or an unregistered redirect_uri never redirects; the user sees a 400 HTML error page instead.

4. Within 60 seconds, exchange the code (form-encoded):

   POST /v1/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&client_id=my-logger&code=<code>
   &redirect_uri=https%3A%2F%2Fmylogger.example%2Foauth%2Fcallback
   &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
   

   A confidential client adds Authorization: Basic base64(client_id:client_secret) (or client_secret= in the form). A public client must not send a secret.

5. Receive access_token, refresh_token, scope, expires_in: 900 and, with openid, id_token. Check that id_token.nonce equals the nonce you sent.

6. Call /v1/sync/* and /v1/oauth/userinfo with Authorization: Bearer <access_token>.

7. Before expires_in elapses, POST /v1/oauth/token with grant_type=refresh_token&client_id=…&refresh_token=…. Store the new refresh_token from every response.

Walkthrough: device flow (CLIs and headless apps)

1. Start the authorization (form-encoded; client authentication as above):

   POST /v1/oauth/device/code
   Content-Type: application/x-www-form-urlencoded
   
   client_id=my-logger&scope=openid%20sync%3Aread
   

   The response carries device_code, user_code (for example KRWG-ZPTL), verification_uri (https://activities.carrierwave.app/v1/oauth/device), verification_uri_complete (…/device?user_code=KRWG-ZPTL), expires_in: 900 and interval: 5.

2. Show the user user_code and verification_uri, or render verification_uri_complete as a QR code. On that page the user types the code, signs in with a magic link, and clicks Allow or Deny.

3. Poll no faster than every interval seconds:

   POST /v1/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
   &client_id=my-logger&device_code=<device_code>
   

   • 400 authorization_pending: keep waiting.
   • 400 slow_down: you polled too fast. The poll window resets even on a rejected poll, so back off by at least interval.
   • 403 access_denied: the user declined. Stop.
   • 400 expired_token: the device code is unknown, expired, or already consumed. Start over.
   • 200 with tokens: approved. The device code is consumed atomically.

4. Use and refresh tokens exactly as in the authorization code flow. The device flow never carries a nonce, so the id_token (with openid) has none.

Discovery

Generic OpenID Connect and OAuth client libraries can configure themselves from the discovery document. A library that honors it will use PKCE S256, authenticate a confidential client with HTTP Basic (preferred) or form fields, and decline to attempt the implicit grant or plain PKCE.

Server metadata

GET /.well-known/openid-configuration
GET /.well-known/oauth-authorization-server

Auth: Public

Served at the domain root, not under /v1. Both paths (the OpenID Connect location and the RFC 8414 alias) return the same document.

No parameters.

Request

GET /.well-known/openid-configuration

Response 200 OK, application/json.

{
  "issuer": "https://activities.carrierwave.app",
  "authorization_endpoint": "https://activities.carrierwave.app/v1/oauth/authorize",
  "token_endpoint": "https://activities.carrierwave.app/v1/oauth/token",
  "userinfo_endpoint": "https://activities.carrierwave.app/v1/oauth/userinfo",
  "revocation_endpoint": "https://activities.carrierwave.app/v1/oauth/revoke",
  "device_authorization_endpoint": "https://activities.carrierwave.app/v1/oauth/device/code",
  "jwks_uri": "https://activities.carrierwave.app/.well-known/jwks.json",
  "scopes_supported": ["openid", "profile", "email", "sync:read", "sync:write"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["EdDSA"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "code_challenge_methods_supported": ["S256"],
  "claims_supported": ["iss", "sub", "aud", "exp", "iat", "auth_time", "nonce", "at_hash",
                       "callsign", "preferred_username", "email", "email_verified"]
}

Errors

Notes

• No cache headers are set on this document. The JWKS document is cacheable for an hour.
• claims_supported describes the ID token and UserInfo. Access tokens carry a different claim set (scope, cs, jti, cid); see Tokens.

Signing keys

GET /.well-known/jwks.json

Auth: Public

Served at the domain root with Cache-Control: public, max-age=3600. Use it to verify access tokens and ID tokens.

No parameters.

Response 200 OK, application/json.

{"keys":[{"kty":"OKP","crv":"Ed25519","use":"sig","alg":"EdDSA","kid":"v1","x":"…"}]}

Authorization code flow

Consent screen

GET /v1/oauth/authorize

Auth: Public (browser page; the user signs in on the page)

Renders the HTML consent page. Every query parameter is optional at the HTTP level so that a malformed link renders a readable error page rather than a bare 400; the page then enforces the required set itself.

Request

GET /v1/oauth/authorize?client_id=my-logger&redirect_uri=https%3A%2F%2Fmylogger.example%2Foauth%2Fcallback&response_type=code&scope=openid%20sync%3Aread&state=abc123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Response 200 OK, text/html; charset=utf-8, Cache-Control: no-store, with <meta name="robots" content="noindex, nofollow">. The page shows the client name, the clamped scope list with the consent copy above, the client’s homepage URL if any (“Developer site: …”), a passphrase warning whenever any sync:* scope is present, a callsign sign-in box, then Allow and Deny buttons. After the user signs in and decides, the page posts the decision to POST /v1/oauth/authorize/decision and sends the browser to the returned redirectUrl.

Errors All are 400 Bad Request HTML pages, never a redirect:

Notes

• The page does not reject a bad response_type or code_challenge_method. Those are caught by the decision endpoint and reported to your app as ?error=… on the redirect.
• Sign-in on the page waits for the magic link for up to 15 minutes.

Consent decision

POST /v1/oauth/authorize/decision

Auth: Bearer (first-party)

Called by the consent page’s own JavaScript with the session the user just created on that page. Your application does not call this endpoint. It is documented so that the redirect you receive is fully explained. Every parameter is re-validated here; nothing from the rendered page is trusted.

Request Content-Type: application/json. The OAuth fields keep their snake_case wire names; only approve is camelCase.

{
  "client_id": "my-logger",
  "redirect_uri": "https://mylogger.example/oauth/callback",
  "response_type": "code",
  "scope": "openid sync:read",
  "state": "abc123",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256",
  "nonce": null,
  "approve": true
}

Response 200 OK, application/json. The URL is always a registered redirect URI. Query values are percent-encoded with an unreserved-only allowlist; if the redirect URI already has a query string the parameters are appended with &.

Approved:

{ "redirectUrl": "https://mylogger.example/oauth/callback?code=Qm3k…48chars…&state=abc123" }

Declined (approve: false):

{ "redirectUrl": "https://mylogger.example/oauth/callback?error=access_denied&state=abc123" }

Malformed but redirectable request (still 200 here; the error goes to your app):

{ "redirectUrl": "https://mylogger.example/oauth/callback?error=invalid_request&state=abc123" }

Possible redirect error values: unsupported_response_type (response_type is not code), invalid_request (empty code_challenge, or code_challenge_method not S256), invalid_scope (nothing left after clamping), access_denied (the user declined).

On approval the server records the user’s consent for your client with the clamped scopes (re-approving revives a previously disconnected app) and issues a single-use authorization code that lives 60 seconds and is bound to the client, the account, the redirect_uri, the scopes, the code_challenge and the nonce. Nothing is persisted on decline.

Errors RFC 6749 body, plus the server envelope for bearer rejections:

Notes

• The scopes placed in the grant and the code are the server’s clamped set, not the raw request.

Device flow

Device verification page

GET /v1/oauth/device

Auth: Public (browser page; the user signs in on the page)

This is the verification_uri returned by POST /v1/oauth/device/code.

Request

GET /v1/oauth/device?user_code=KRWG-ZPTL

Response 200 OK, text/html; charset=utf-8, Cache-Control: no-store, noindex. Shows a code input (placeholder XXXX-XXXX), the callsign sign-in box, Allow and Deny buttons, and the notice “Only approve a code you started yourself, on a device you are holding.” On decision the page posts to POST /v1/oauth/device/decision and then shows “ is now connected” or “Request denied. Nothing was shared.”

Errors

Notes

• The page always renders 200, whether or not user_code is valid. Validity is checked only at decision time.

Start a device authorization

POST /v1/oauth/device/code

Auth: Client credentials (same rules as the token endpoint: a confidential client must present its secret, a public client must not)

Request Content-Type: application/x-www-form-urlencoded

POST /v1/oauth/device/code
Content-Type: application/x-www-form-urlencoded

client_id=my-cli&scope=openid%20sync%3Aread

Response 200 OK, application/json, Cache-Control: no-store.

{
  "device_code": "Xy7…48 alphanumerics…",
  "user_code": "KRWG-ZPTL",
  "verification_uri": "https://activities.carrierwave.app/v1/oauth/device",
  "verification_uri_complete": "https://activities.carrierwave.app/v1/oauth/device?user_code=KRWG-ZPTL",
  "expires_in": 900,
  "interval": 5
}

Errors RFC 6749 body:

Notes

• user_code is XXXX-XXXX drawn from the 25-character ambiguity-free alphabet ACDEFGHJKMNPQRTUVWXY34679. Typed input is normalized (case, dash, spaces), so the user can enter krwgzptl.
• interval is enforced. A poll inside the window returns slow_down and resets the window.
• Scopes are clamped again at decision time, so a ceiling tightened between issue and approval is honored.

Device decision

POST /v1/oauth/device/decision

Auth: Bearer (first-party)

Called by the device verification page with the session the user created there. Your application does not call this endpoint.

Request Content-Type: application/json, camelCase.

{ "userCode": "KRWG-ZPTL", "approve": true }

Response 200 OK, application/json.

{ "approved": true, "clientName": "My CLI" }

On approval the server records the user’s consent for the client with the re-clamped scopes and marks the device code approved; the polling client’s next token request succeeds. A denial is terminal: the polling client receives access_denied and the code cannot be re-approved.

Errors RFC 6749 body, plus the server envelope for bearer rejections:

Tokens

Access-token claims: iss (https://activities.carrierwave.app), sub (the account UUID), aud (cw-social), scope (space-delimited), cs (primary callsign, informational only), iat, exp, jti, cid (your client id). The JWT header carries alg: EdDSA and kid.

ID-token claims: iss, sub, aud (your client_id), iat, exp, auth_time, nonce (only when the authorization request carried one; the device flow never sets it), at_hash (base64url of the left 16 bytes of SHA-256 of the access token), callsign, preferred_username (mirrors callsign), and email with email_verified: true (only with the email scope and a verified address on file). auth_time is the moment of consent.

Verify both token types against GET /.well-known/jwks.json.

Revocation: disconnecting an app (DELETE /v1/oauth/grants/:client_id), client-side revocation (POST /v1/oauth/revoke) and client suspension all stop new tokens immediately, but access tokens already issued stay valid for up to 15 minutes because verification is stateless. Plan for that window.

Token endpoint

POST /v1/oauth/token

Auth: Client credentials. A confidential client must present its secret, either as Authorization: Basic base64(client_id:client_secret) or as client_secret in the form; HTTP Basic wins if both are present. A public client must not send a secret.

Request Content-Type: application/x-www-form-urlencoded

Authorization-code example:

POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=my-logger&code=Qm3k…&redirect_uri=https%3A%2F%2Fmylogger.example%2Foauth%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Refresh example (confidential client, HTTP Basic):

POST /v1/oauth/token
Authorization: Basic bXktc2VydmVyOmN3c19…
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=cwr_9f3a…64hex…

Device poll example:

POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&client_id=my-cli&device_code=Xy7…48chars…

Response 200 OK, application/json, Cache-Control: no-store, Pragma: no-cache.

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSIsImtpZCI6InYxIn0…",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "cwr_9f3a…",
  "scope": "openid sync:read",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSIsImtpZCI6InYxIn0…"
}

refresh_token is always present. id_token is omitted (not null) when openid is not in the granted scopes, and is always omitted on refresh_token grants.

Per-grant behavior:

• authorization_code: consumes the code atomically (unknown, expired and already-used codes are indistinguishable), checks that the code was issued to this client, checks redirect_uri equality, verifies PKCE, then issues tokens.
• refresh_token: checks that the presented token belongs to this client before rotating it, rotates it (reuse outside the 60-second grace window revokes the family), requires the user’s consent to still exist, and issues tokens whose scopes are the intersection of the token’s scopes, the current consent and the client ceiling.
• device grant: returns the RFC 8628 section 3.5 errors until the user decides; on approval the device code is consumed and tokens are issued with the scopes recorded at decision time.

Errors RFC 6749 body, with Cache-Control: no-store:

Notes

• invalid_grant is one code, but error_description differs per cause (listed above), so you can tell a PKCE failure from a redirect mismatch by its text.
• Refresh tokens from Carrier Wave’s own apps cannot be used here (invalid_grant), and refresh tokens issued here cannot be used at /v1/auth/token/refresh (403 FORBIDDEN).
• The user’s consent is re-checked on every refresh, so a disconnect takes effect at the next refresh, not at the 60-day expiry.

Revoke a refresh token

POST /v1/oauth/revoke

Auth: Client credentials (same rules as the token endpoint)

RFC 7009 revocation for refresh tokens.

Request Content-Type: application/x-www-form-urlencoded

token_type_hint is not read.

POST /v1/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=cwr_9f3a…&client_id=my-logger

Response 200 OK with an empty body, whether or not the token existed or belonged to the caller (RFC 7009 section 2.2).

Errors RFC 6749 body:

Notes

• Revocation only happens if the token was issued to the calling client; otherwise the request is silently ignored.
• Revokes the whole rotation family, not just the presented token.
• Does not revoke the user’s consent. The user stays connected to your app; you simply have no live refresh token until the user authorizes again. Access tokens already issued remain valid for up to 15 minutes.

Identity and connected apps

UserInfo

GET /v1/oauth/userinfo

Auth: Bearer (third-party, scope openid). Carrier Wave’s own apps may also call it. This is the only OAuth route reachable with a third-party token.

No parameters.

Request

GET /v1/oauth/userinfo
Authorization: Bearer eyJ0eXAiOiJKV1Qi…

Response 200 OK, application/json. email and email_verified appear only when the token carries the email scope and a verified address exists; otherwise both keys are omitted.

{
  "sub": "4c7a4c0e-7e0b-4f3a-9d8f-2a6e1b7a9c21",
  "callsign": "W6JY",
  "preferred_username": "W6JY",
  "email": "w6jy@example.com",
  "email_verified": true
}

Errors server envelope {"error":{"code","message"}}:

Notes

• sub is the account UUID and matches sub in the access token and the ID token.
• callsign is resolved from the account at request time, not from the token’s cs claim.
• email prefers the address the primary callsign was verified under.
• profile is not checked; callsign and preferred_username are always returned.

List connected applications

GET /v1/oauth/grants

Auth: Bearer (first-party)

Lists the apps the signed-in user has connected. Used by Carrier Wave’s own apps; third-party tokens are denied.

No parameters.

Request

GET /v1/oauth/grants
Authorization: Bearer <first-party access token>

Response 200 OK, { "data": [...] }, newest first, disconnected apps excluded.

{
  "data": [
    {
      "clientId": "my-logger",
      "clientName": "My Logger",
      "scopes": "openid sync:read sync:write",
      "grantedAt": "2026-10-09T18:22:41.120394Z"
    }
  ]
}

Errors server envelope:

Notes

• scopes is the space-delimited string as last consented; re-consent overwrites it.
• grantedAt is RFC 3339 in UTC.

Disconnect an application

DELETE /v1/oauth/grants/:client_id

Auth: Bearer (first-party)

Request

DELETE /v1/oauth/grants/my-logger
Authorization: Bearer <first-party access token>

Response 204 No Content, empty body.

The user’s consent is revoked and the client’s refresh tokens for this account are removed. The client’s next refresh fails with invalid_grant; access tokens it already holds remain valid for up to 15 minutes.

Errors server envelope:

Notes

• A second DELETE for the same client returns 403.
• Authorizing the app again later restores the connection.

Operator endpoints

Clients are registered, listed and suspended by Carrier Wave staff; these endpoints are not available to third-party developers.

Challenges, progress and leaderboards

A challenge is an operator-authored goal that participants join and report progress against: work all 50 US states, reach 1000 park contacts, take part in a time-boxed event. The server stores each challenge with a free-form configuration object. Your client evaluates QSOs locally against that configuration and sends the server a summary. The server turns the summary into a score, a tier, a percentage and a leaderboard rank.

These endpoints are first-party only. Third-party OAuth tokens receive 403 FORBIDDEN on every route in this section. The public reads (list and get challenge, leaderboard, badge image) need no token at all.

Conventions

• All paths are under /v1. Responses are JSON unless noted. Success bodies are wrapped as {"data": ...}; errors as {"error": {"code", "message", "details"?}}.
• An invalid UUID in a path answers 400 VALIDATION_ERROR. A missing or malformed JSON body (including a missing Content-Type: application/json) answers 400 VALIDATION_ERROR. A query string that fails to parse (for example active=maybe or limit=abc) answers a plain-text 400 without the JSON envelope. An unknown /v1/... path answers 404 NOT_FOUND.
• Request bodies are capped at 1 MiB on every route.
• Requests are rate limited per IP at 10 requests per second with a burst of 20. Excess requests receive 429. No rate-limit headers are returned.
• Cross-origin browser requests are accepted from https://carrierwave.app and https://activities.carrierwave.app.
• Callsigns are stored and compared upper-case.

Auth levels used below

• Public (optional bearer). A valid first-party bearer, if present, identifies the caller. A missing, invalid, expired or third-party token downgrades the request to anonymous. These routes never answer 401 or 403 for a bad optional token.
• Bearer (first-party). A device token (fd_..., issued by the join endpoint) or a first-party OAuth access token. Missing or invalid: 401 INVALID_TOKEN. Third-party OAuth token: 403 FORBIDDEN.
• Operator. An operator token. Any failure answers 401 INVALID_TOKEN.

Types and categories

type and category are labels used for filtering and display.

Progress maths use configuration.goals.type and configuration.scoring.method, not the type label. A challenge has ended when isActive is false. The server does not evaluate timeConstraints dates.

How progress works

1. The client evaluates QSOs locally against configuration.qualificationCriteria, timeConstraints and historicalQsosAllowed, then sends a summary (completedGoals, currentValue, qualifyingQsoCount, lastQsoDate) to POST /v1/challenges/:id/progress. The server stores the summary as sent. It does not see QSOs and does not check completedGoals against goals.items.
2. The server derives three values from the summary and the configuration:
   • score, from scoring.method. count (the default) is the number of completedGoals. percentage is floor(completed / number of goals.items * 100), or 0 when there are no items. points is currentValue. Any other value, including weighted, behaves as count.
   • currentTier. The server walks configuration.tiers in array order and keeps the last tier whose integer threshold is less than or equal to the score. tiers[].order is not used, so list tiers in ascending threshold order. If tiers is absent, or any tier lacks a numeric threshold, currentTier is null.
   • percentage, from goals.type. collection: completed / number of goals.items * 100. cumulative: currentValue / goals.targetValue * 100 (targetValue defaults to 100). Anything else: 0.0. The value is not clamped to 100.
3. Each report replaces the previous one for that callsign and challenge and stamps the update time. The update time is the leaderboard tiebreaker: the earlier update wins.
4. rank orders all reported progress for the challenge by score descending, then earliest update. Ties share a rank and the following rank is skipped. scoring.tiebreaker is stored but not applied.
5. newBadges in the progress response is currently always empty. Badges are not awarded by the server.

Tiers and badges

Tiers are milestone thresholds inside configuration.tiers. Badges are images uploaded by an operator and optionally tagged with a tierId; the tierId is not validated against the configuration. Badge images are served publicly by id (GET /v1/badges/:id/image). There is no public badge listing, and the challenge object does not include a badges array; tiers in the configuration may carry a badgeId.

Invite-only challenges

A challenge requires an invite when inviteConfig.requiresToken is true. Nothing else in inviteConfig is read: maxParticipants and expiresAt are passed through and not enforced. Invite tokens have the form inv_ followed by 24 characters from [0-9a-z]. Operators mint them with optional maxUses and expiresAt. A join validates the token first for a precise error, then redeems it atomically, so concurrent joins cannot exceed maxUses. A join that fails after redemption releases the use.

Device token on join

POST /v1/challenges/:id/join is how a device without an account obtains its fd_ device token.

• If the callsign is new to the server, a participant record is created with a fresh token and the token is returned once in deviceToken.
• If the callsign already exists, the caller must already be authenticated as that exact callsign, otherwise the join answers 403 FORBIDDEN. The token is never rotated or re-disclosed; deviceToken is omitted from the response. Recovering a lost token is handled by the magic-link sign-in flow, not this endpoint.
• A caller using a first-party OAuth token always takes the second branch: the participant record already exists for an OAuth caller, so an OAuth caller never receives a deviceToken.

Challenge configuration schema

Wire shape of configuration (camelCase). “Server reads” marks the keys the server inspects; everything else is stored and echoed verbatim for the client to interpret. “Required” marks keys the official clients expect to be present; the server does not validate the configuration.

inviteConfig (separate top-level field, nullable):

hamalertConfig (separate top-level field, nullable): {enabled: boolean, alertType: string, spotSources: string[], autoManage: boolean}. Passed through; the server does not read it.

Browsing challenges

List challenges

GET /v1/challenges

Auth: Public (optional bearer; a bearer changes nothing in the response)

Request: no body.

Response: 200 OK

{
  "data": {
    "challenges": [
      {
        "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "ARRL WAS 250",
        "description": "Work all 50 US states during 2026 ...",
        "category": "award",
        "type": "collection",
        "participantCount": 1234,
        "isActive": true
      }
    ],
    "total": 45,
    "limit": 50,
    "offset": 0
  }
}

participantCount counts participants with status active. Results are ordered newest first. total is the number of challenges matching the filters, ignoring paging. limit echoes the applied value.

Errors

Notes: List items do not include configuration, version, author or timestamps. Fetch the challenge by id for those.

Get challenge

GET /v1/challenges/:id

Auth: Public (optional bearer; no effect on the response)

Response: 200 OK

Response headers:

{
  "data": {
    "id": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
    "version": 1,
    "name": "DXCC",
    "description": "Work 100 or more DXCC entities ...",
    "author": "ARRL",
    "category": "award",
    "type": "collection",
    "configuration": {
      "goals": {
        "type": "collection",
        "items": [
          { "id": "1", "name": "Canada", "category": "entity" }
        ]
      },
      "tiers": [
        { "id": "tier-50",  "name": "50 Entities", "threshold": 50,  "order": 1 },
        { "id": "tier-100", "name": "DXCC",        "threshold": 100, "order": 2 }
      ],
      "qualificationCriteria": {
        "bands": null,
        "modes": null,
        "requiredFields": [],
        "dateRange": null,
        "matchRules": [
          { "qsoField": "dxccEntity", "goalField": "id", "transformation": "none" }
        ]
      },
      "historicalQsosAllowed": true,
      "scoring": {
        "method": "count",
        "tiebreaker": "earliestCompletion",
        "displayFormat": "{value} entities"
      }
    },
    "inviteConfig": null,
    "hamalertConfig": null,
    "isActive": true,
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Fields: id, version, name, description, author (nullable), category, type, configuration, inviteConfig (nullable), hamalertConfig (nullable), isActive, createdAt, updatedAt. There is no badges array.

Errors

Notes: inviteConfig is returned verbatim, so a client can check requiresToken before attempting to join. Inactive challenges are still readable. version increments on every operator update, and ETag and X-Challenge-Version change with it.

Participation and progress

Join a challenge

POST /v1/challenges/:id/join

Auth: Public (optional bearer). A bearer is required when the callsign is already known to the server: the request must then be authenticated as that same callsign or it answers 403 FORBIDDEN. For a brand-new callsign no bearer is needed and this call issues the device token.

Request (camelCase):

{
  "callsign": "W1ABC",
  "deviceName": "iPhone",
  "inviteToken": "inv_k3j5h2g8f7d6s5a4p0o9i8u7"
}

Processing order:

1. Challenge lookup; unknown id answers 404.
2. isActive is false: 400 CHALLENGE_ENDED. Only the flag is checked; timeConstraints dates are not evaluated.
3. If requiresToken: the token must be non-empty, exist, and belong to this challenge, otherwise 403 INVITE_REQUIRED. Expired: 403 INVITE_EXPIRED. useCount >= maxUses: 403 INVITE_EXHAUSTED.
4. The participant record is found or created.
5. Existing participant and caller not authenticated as that callsign: 403 FORBIDDEN.
6. Atomic invite redemption. If the token expired or ran out between steps 3 and 6, or the join lost a race: 403 INVITE_EXHAUSTED.
7. Participation is recorded. If a participation already exists for this challenge and callsign: 409 ALREADY_JOINED, and the invite use is released.

Response: 201 Created

{
  "data": {
    "participationId": "0f9c1c2e-6c1a-4d8e-9a7b-3c2d1e0f9a8b",
    "deviceToken": "fd_AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "joinedAt": "2025-01-15T12:00:00Z",
    "status": "active",
    "historicalAllowed": true
  }
}

deviceToken is present only when this call created the participant; for an existing callsign it is omitted entirely. status is always "active" on a fresh join. historicalAllowed echoes configuration.historicalQsosAllowed (default true).

Errors

Notes

• The device token is shown once; the app must store it.
• Gated joins increment the invite’s useCount.
• Joining does not create a progress record. The participant is absent from the leaderboard until the first progress report.

Report progress

POST /v1/challenges/:id/progress

Auth: Bearer (first-party)

Request:

{
  "completedGoals": ["CA", "NY", "TX"],
  "currentValue": 47,
  "qualifyingQsoCount": 52,
  "lastQsoDate": "2025-01-15T18:30:00Z"
}

Response: 200 OK (not 201)

{
  "data": {
    "accepted": true,
    "serverProgress": {
      "completedGoals": ["CA", "NY", "TX"],
      "currentValue": 47,
      "percentage": 6.0,
      "score": 3,
      "rank": 23,
      "currentTier": null
    },
    "newBadges": []
  }
}

• accepted is always true.
• serverProgress.completedGoals and currentValue echo the request.
• percentage (floating point, not capped at 100), score and currentTier are computed as described in “How progress works”. rank is the rank after this report is applied.
• newBadges is an array of badge ids and is currently always empty.

Errors

Notes

• Each report fully replaces the previous one and refreshes the update time, which moves the reporter later in tie ordering.
• Progress is accepted for inactive challenges; isActive is not checked here.

Get progress

GET /v1/challenges/:id/progress

Auth: Bearer (first-party)

Response: 200 OK

{
  "data": {
    "completedGoals": ["CA", "NY", "TX"],
    "currentValue": 47,
    "percentage": 6.0,
    "score": 3,
    "rank": 23,
    "currentTier": null
  }
}

score and currentTier are the stored values from the last report. percentage is recomputed from the stored report and the current configuration. rank is live.

Errors

Leave a challenge

DELETE /v1/challenges/:id/leave

Auth: Bearer (first-party)

Request: no body.

Response: 204 No Content, empty body.

Errors

Notes

• Leaving marks the participation left and deletes the caller’s progress, in one transaction. A second leave call answers 403 and changes nothing.
• After leaving, the callsign no longer appears in GET /v1/participants/:callsign/challenges (active only) or on the leaderboard (progress deleted).
• Leaving a challenge is permanent. A later POST /v1/challenges/:id/join for the same callsign answers 409 ALREADY_JOINED.
• Invite uses are not refunded.

Get participation status

GET /v1/challenges/:id/participants/:callsign

Auth: Bearer (first-party); the authenticated callsign must equal :callsign (case-insensitive)

Response: 200 OK

{
  "data": {
    "participationId": "0f9c1c2e-6c1a-4d8e-9a7b-3c2d1e0f9a8b",
    "challengeId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "joinedAt": "2025-01-15T12:00:00Z",
    "status": "active"
  }
}

status is one of active, left, completed. The server currently writes only active and left.

Errors

List a callsign’s challenges

GET /v1/participants/:callsign/challenges

Auth: Bearer (first-party); :callsign must be the caller’s own

Response: 200 OK. Note that data is a bare array.

{
  "data": [
    {
      "participationId": "0f9c1c2e-6c1a-4d8e-9a7b-3c2d1e0f9a8b",
      "challengeId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "challengeName": "ARRL WAS 250",
      "joinedAt": "2025-01-15T12:00:00Z",
      "status": "active"
    }
  ]
}

Only participations with status active are returned, most recent join first. Inactive challenges are still listed.

Errors

Leaderboards

Get leaderboard

GET /v1/challenges/:id/leaderboard

Auth: Public (optional bearer; the bearer is ignored. userPosition comes from the around parameter, never from the caller’s identity)

Response: 200 OK

{
  "data": {
    "leaderboard": [
      {
        "rank": 1,
        "callsign": "K1ABC",
        "score": 50,
        "currentTier": "tier-50",
        "completedAt": "2025-01-10T00:00:00Z"
      },
      {
        "rank": 2,
        "callsign": "W1ABC",
        "score": 47,
        "currentTier": "tier-40",
        "completedAt": "2025-01-12T08:15:00Z"
      }
    ],
    "total": 1234,
    "userPosition": null,
    "lastUpdated": "2025-01-15T19:00:00Z"
  }
}

Entry fields: rank (integer), callsign, score, currentTier (nullable), completedAt (nullable). userPosition is either null or an object of the same shape.

Ranking

• Only participants who have reported progress at least once appear. total is the number of such participants, not the participant count.
• rank orders by score descending, then earliest update. Ties share a rank and the following rank is skipped (standard rank, not dense rank). scoring.tiebreaker is not applied.
• completedAt is not a completion timestamp. It is the time of the participant’s latest report when score > 0, otherwise null. It moves on every report.
• lastUpdated is the server time when the response was built, not a data freshness marker.

around behaviour

• around returns a fixed window of five ranks either side of the named callsign (rank between target minus 5 and target plus 5, ordered by rank) and ignores limit and offset. With ties the window can hold more or fewer than 11 rows.
• If the callsign has no reported progress, leaderboard is [] and userPosition is null; total is still the full count.
• The callsign is upper-cased for the lookup, but userPosition is the entry whose callsign equals the around value exactly as supplied. Pass the callsign in upper case: around=w1abc returns the window but userPosition: null.

Errors

Badges

Get badge image

GET /v1/badges/:id/image

Auth: Public (optional bearer; ignored)

Response: 200 OK, body is the raw image bytes.

No ETag or Last-Modified is set.

Errors

Notes: Badges are deleted with their challenge, after which cached copies may outlive the badge for up to a day. Badge ids and the relative imageUrl (/v1/badges/:id/image) are issued to operators at upload time; prefix imageUrl with the API origin.

Operator endpoints

All operator endpoints require an operator token in Authorization: Bearer ...; any failure answers 401 INVALID_TOKEN. Request and response bodies are not documented here.

Programs

A program is an entry in the on-the-air activity registry: Parks on the Air (POTA), Summits on the Air (SOTA), WWFF, IOTA, LOTA, Agents on Air, and the catch-all casual. Clients load the registry at startup and use it to drive reference entry, reference validation, feature switches, and ADIF export. The registry is read-only for third parties.

Every success body in this section is wrapped as {"data": ...}. Every error body is {"error": {"code": "...", "message": "...", "details": {...}}}, where details is optional. Field names are camelCase. Malformed JSON bodies and bad path parameters return 400 VALIDATION_ERROR. Request bodies are capped at 1 MiB.

Program record

Field presence rules:

• website, referenceFormat, referenceExample, and activationThreshold are always present and may be null.
• iconUrl, serverBaseUrl, adifFields, and dataEntry are omitted when unset.
• isActive is always present.

Versioning and caching

The list endpoint returns a numeric version: the Unix epoch seconds of the most recent update among active programs, or 0 when there are none. Any change to an active program moves it. No ETag or Cache-Control headers are emitted and conditional requests are not supported. Cache the list, store version, and re-fetch when it differs.

List programs

GET /v1/programs

Auth: Public (optional bearer; the response is identical with or without a token).

No parameters.

Response: 200 OK

{
  "data": {
    "programs": [
      {
        "slug": "pota",
        "name": "Parks on the Air",
        "shortName": "POTA",
        "icon": "tree",
        "website": "https://pota.app",
        "referenceLabel": "Park Reference",
        "referenceFormat": "^[A-Z]+-[0-9]{4,5}$",
        "referenceExample": "K-0001",
        "multiRefAllowed": true,
        "activationThreshold": 10,
        "supportsRove": true,
        "capabilities": ["referenceField", "adifUpload", "browseSpots", "selfSpot", "hunter", "locationLookup", "progressTracking"],
        "adifFields": {
          "mySig": "POTA",
          "mySigInfo": "MY_POTA_REF",
          "sigField": "SIG",
          "sigInfoField": "SIG_INFO"
        },
        "isActive": true
      },
      {
        "slug": "aoa",
        "name": "Agents on Air",
        "shortName": "AoA",
        "icon": "antenna.radiowaves.left.and.right",
        "website": null,
        "referenceLabel": "Mission Reference",
        "referenceFormat": "^M-[a-z0-9]{4}$",
        "referenceExample": "M-a01f",
        "multiRefAllowed": false,
        "activationThreshold": null,
        "supportsRove": false,
        "capabilities": ["referenceField", "hunter", "dataEntry", "dataVerification"],
        "dataEntry": {
          "label": "Passkey",
          "placeholder": "Enter code from other station",
          "format": null
        },
        "isActive": true
      }
    ],
    "version": 1737900000
  }
}

Errors:

Notes:

• Only active programs are returned, in display order.
• No ETag is emitted; poll version instead.

Get a program

GET /v1/programs/:slug

Auth: Public (optional bearer; the response is identical with or without a token).

Response: 200 OK with {"data": <Program>}, the same shape as a list item above.

Errors:

Notes: Inactive programs are not distinguishable from missing ones on this endpoint.

Operator endpoints

These require an operator token and are not available to third-party integrations.

Achievements

Achievements are shown to users as “Badges”. There are two kinds of record:

• Catalog entries describe each badge: id (kebab-case string), name, description, category (creator, community, activity, ecosystem, streak, quirky), tier (bronze, silver, gold, or null), iconName (SF Symbol), accentHex, awardMethod, secret, sortOrder. The catalog is maintained by Carrier Wave; there is no API to add entries.
• Awards record that a callsign holds a badge: id (UUID), callsign, achievementId, awardedAt, awardedBy, evidence (arbitrary JSON or null). A callsign holds each badge at most once.

Award methods

awardMethod on a catalog entry says who may grant the badge.

Signals. A signal is a one-line claim from a signed-in first-party client, such as “this user paired with Sweep”. The server accepts a signal only for catalog entries whose awardMethod is signal, so a client cannot claim manual or auto badges. The award is written with awardedBy set to signal. After a signal the server also checks for the cross-platform badge: it is granted when the callsign holds sweep-user and at least one of watch-operator, home-screen, or pebble-pioneer, both awarded within the last 7 days. That award has awardedBy set to system and evidence of {"windowDays": 7}.

Auto badges. Some auto badges are evaluated as soon as an activity is recorded: first-qso, first-cw, first-ssb, first-ft8, and mode-polyglot (five or more distinct modes), plus a small number of secret badges. Others are cumulative and are evaluated by a background evaluator that runs periodically over recently active callsigns: qso-100, qso-1000, qso-10000 (total QSOs), dxcc-10, dxcc-100 (distinct DXCC entities), all-hf (distinct bands), streak-7, streak-30, streak-365 (longest daily streak), and anniversary (account at least one year old). Auto awards are idempotent; re-evaluation never duplicates an award.

Refreshing on the client

• Fetch the catalog once and cache it. Entries change rarely.
• Fetch a callsign’s awards when showing a profile, and again after the user logs activity or after sending a signal. Auto awards can appear minutes after the activity that earned them.
• Send each signal once. Re-sending is harmless but unnecessary.
• No ETag or Cache-Control headers are emitted on these endpoints.

List the achievement catalog

GET /v1/achievements

Auth: Public (optional bearer; the response is identical with or without a token).

No parameters.

Response: 200 OK

{
  "data": {
    "achievements": [
      {
        "id": "first-qso",
        "name": "First QSO",
        "description": "Logged your first contact",
        "category": "activity",
        "tier": null,
        "iconName": "antenna.radiowaves.left.and.right",
        "accentHex": "#4CAF50",
        "awardMethod": "auto",
        "secret": false,
        "sortOrder": 100
      },
      {
        "id": "qso-100",
        "name": "Centurion",
        "description": "Logged 100 contacts",
        "category": "activity",
        "tier": "bronze",
        "iconName": "antenna.radiowaves.left.and.right",
        "accentHex": "#CD7F32",
        "awardMethod": "auto",
        "secret": false,
        "sortOrder": 110
      }
    ]
  }
}

Errors:

Notes:

• Secret achievements (secret: true) are excluded. Every entry returned has secret: false.
• Ordered by sortOrder ascending, then id ascending.

List a callsign’s achievements

GET /v1/users/:callsign/achievements

Auth: Public (optional bearer; the response is identical with or without a token). Anyone can read anyone’s awards.

Response: 200 OK

{
  "data": {
    "callsign": "W6JY",
    "awards": [
      {
        "id": "3f2a9c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
        "callsign": "W6JY",
        "achievementId": "creator",
        "awardedAt": "2026-03-01T18:22:10.512345Z",
        "awardedBy": "system",
        "evidence": null
      }
    ]
  }
}

Errors:

Notes:

• An unknown callsign returns 200 with an empty awards array. There is no 404.
• Awards of secret achievements are included even though the catalog omits them. A client that cannot match an achievementId to a catalog entry should skip it or render it generically.
• Ordered by awardedAt descending.
• evidence is whatever the awarding path recorded, for example {"from": "sessionCompleted"}, {"total": 1234}, or {"windowDays": 7}, or null.

Report an achievement signal

POST /v1/users/me/achievements/signal

Auth: Bearer (first-party). The award is always written for the token’s own callsign; the body cannot name another user. Third-party OAuth tokens are refused.

No path or query parameters.

Request:

{ "id": "watch-operator" }

Response: 201 Created with the award.

{
  "data": {
    "id": "9d1b6e42-0c3a-4f5e-8b7d-2a1c3e5f7a9b",
    "callsign": "N0CALL",
    "achievementId": "watch-operator",
    "awardedAt": "2026-10-10T17:03:41.120934Z",
    "awardedBy": "signal",
    "evidence": null
  }
}

Errors:

Notes:

• Idempotent. Re-sending the same signal returns 201 again with the original awardedAt. awardedBy is set to signal on every call. evidence is replaced only when the new request supplies a non-null value.
• Any cross-platform award triggered by the signal is not included in this response. Fetch the callsign’s awards to see it.
• Accepted ids: sweep-user, watch-operator, home-screen, pebble-pioneer, swl, rbn-spotter.

Operator endpoints

These require an operator token and are not available to third-party integrations.

Contest definitions

A contest definition is a declarative JSON document describing one amateur-radio contest: schedule, exchange, dupe rules, scoring phases, operating constraints, Cabrillo header, and entry categories. The current format version is 0.3.0. Definitions are published by Carrier Wave and are read-only for third parties.

File vs. contest. A file has a version and a contests array. Each contest in the file is stored and served individually, keyed by its id. The file-level version is served as formatVersion on each contest.