API documentation

Everything apps can do with TKDchecker, version 1. JSON over HTTPS.

Base URL

https://www.tkdchecker.com//api/v1 · Machine-readable: OpenAPI

Two kinds of access

• Public data: academies, schedules, events and public profiles. Send your app's client id in the X-Client-Id header.
• For a member: their own data and everything that writes. The member signs in on TKDchecker and allows your app (OAuth 2.0, authorization code with PKCE). You get an access token for one hour and a refresh token.

curl https://www.tkdchecker.com//api/v1/academies?q=gracie \
  -H "X-Client-Id: bcapp_your_client_id"

Signing a member in

1. Send the member to the authorize page with a code challenge (S256):

https://www.tkdchecker.com//oauth/authorize?response_type=code
  &client_id=bcapp_your_client_id
  &redirect_uri=https://yourapp.com/callback
  &scope=profile:read%20training:write
  &state=random_value
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

2. The member allows the app and comes back to your redirect URI with ?code= and your state. 3. Exchange the code:

curl -X POST https://www.tkdchecker.com//oauth/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://yourapp.com/callback \
  -d client_id=bcapp_your_client_id \
  -d client_secret=YOUR_SECRET \
  -d code_verifier=THE_VERIFIER

Mobile and browser apps register as public clients: they have no secret and must use PKCE. Refresh with grant_type=refresh_token (the refresh token changes every time). Revoke with POST /oauth/revoke.

curl -X POST https://www.tkdchecker.com//api/v1/me/training \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2e" \
  -d '{"date":"2026-10-01","type":2,"minutes":90,"rounds":6,"style":"gi"}'

Scopes

• profile:read See your profile, belt, promotion history and verification status
• training:read See your training log and check-ins
• training:write Log training for you, and edit or delete the sessions this app logged needs approval
• checkins:write Check you in to classes at your academies needs approval
• events:write Mark events you are going to needs approval
• club:attendance Register attendance at academies you run, for members who allowed this app needs approval

Write scopes are open to an app once we have approved it: ask on your app's page. Apps can never vote, change belts, promotions or verification, send messages or touch payments.

Limits

• 10,000 calls a day per app (more on request) and 120 a minute per member or IP.
• Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429.
• Lists are paged: pass next_cursor back as ?cursor= until it is null.
• Send an Idempotency-Key header with writes: a retry with the same key never writes twice.

Errors

{"error": {"code": "insufficient_scope", "message": "The token lacks the 'training:write' scope."}}

Privacy

Public data only shows adults with a public profile who have not turned off "Show me in apps". Use the data only for what the member allowed, and delete it when they disconnect your app.

Your member

Training log

Academies

Club attendance

Members

Events

Reference