GraphQL API and API keys

Everything the app, the CLI and the MCP server do goes through one GraphQL API at /api/graphql. The TypeScript SDK is the easiest way to use it. For anything else (a shell script, a home dashboard, another language) you can send raw GraphQL with a personal API key.

Create a key

Open Settings → API keys in the app, give the key a name, choose its access and expiry, and select Create key.

• Read only keys can run queries. Every mutation is refused.
• Read and write keys can run queries and mutations.
• Expiry is 30 days, 90 days, a year, or never.

The full key (it starts with gg_) is shown once, right after you create it. gymgym stores only a hash of it and its first characters, so copy it then. If you lose it, revoke it and create another.

Call the API

Send the key as a Bearer token:

curl -X POST https://gymgym.club/api/graphql \
  -H "authorization: Bearer gg_your_key" \
  -H "content-type: application/json" \
  -d '{"query":"{ viewer { workouts(limit: 5) { date name } } }"}'

The x-api-key: gg_your_key header works too. On a self-hosted server, use its address. Every query, mutation and type is listed in the GraphQL reference, and the schema is in the repository at packages/sdk/schema.graphql, so code generators for other languages can use it.

A mutation with a write key looks like this:

curl -X POST https://gymgym.club/api/graphql \
  -H "authorization: Bearer gg_your_key" \
  -H "content-type: application/json" \
  -d '{"query":"mutation($input: BodyweightInput!) { logBodyweight(input: $input) { date weight } }","variables":{"input":{"date":"2026-10-04","weight":72.5}}}'

Limits

A key acts as you, on your data only, with the same row rules as the app (see Data isolation). It is deliberately narrower than a sign-in:

• it works only on /api/graphql. It is not a session for sign-in pages or the MCP server;
• it cannot create, list or revoke keys, manage connected apps or signed-in devices, or use admin tools, even if you are an admin;
• each key may make 120 requests a minute. Above that, requests fail with the RATE_LIMITED error code until the minute is over.

A request with a revoked, expired or unknown key is answered as signed out: viewer is null and mutations fail with FORBIDDEN.

Revoke a key

Settings → API keys lists each key with its name, first characters, access, and when it was created, last used and expires. Revoke deletes it at once, and the next request with it fails. Deleting your account deletes its keys.

Signed-in devices

Settings → Signed-in devices lists every browser and command line signed in to your account. The CLI appears as “gymgym CLI”. Sign out ends that session; the device has to sign in again. A browser can keep a cached session for up to five minutes after you sign it out.