BalkTalk

For developers

Sign in with BalkTalk

A standard OAuth 2.1 authorization code flow with PKCE: the member grants access on BalkTalk, you get a code and exchange it for a token.

Addresses

What Address
Consent screen https://www.balktalk.net/oauth/authorize
Tokens https://www.balktalk.net/oauth/token
Public API https://www.balktalk.net/api/dev/v1

1. Create a PKCE pair

For every sign-in create a random code_verifier (43 to 128 characters) and its challenge code_challenge = base64url(SHA-256(verifier)). You keep the verifier and send the challenge.

function base64url(bytes) {
  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
}

const verifier = base64url(crypto.getRandomValues(new Uint8Array(48)))
const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
const challenge = base64url(new Uint8Array(hash))

PKCE is required for apps without a client secret. We recommend it with a secret too.

https://www.balktalk.net/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-site.example/callback
  &scope=identity scores
  &state=RANDOM_VALUE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256
Parameter Meaning
client_id The Client ID from the portal
redirect_uri A redirect address, exactly as entered in the portal
scope Scopes separated by spaces. identity is always implied
state Your random value. When the member returns, check it is the same
code_challenge The PKCE challenge from step one

A member who is not signed in signs in to BalkTalk first. Then they see the consent screen with the name and icon of your app and the list of scopes. If they have already granted the same scopes, the screen is skipped.

3. The member returns with a code

When they allow:

https://your-site.example/callback?code=CODE&state=RANDOM_VALUE

When they deny:

https://your-site.example/callback?error=access_denied&state=RANDOM_VALUE

The code is valid for 10 minutes and can be used once.

4. Exchange the code for a token

An app without a client secret:

curl -X POST https://www.balktalk.net/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "https://your-site.example/callback",
    "code": "CODE",
    "code_verifier": "VERIFIER"
  }'

An app with a server adds "client_secret": "CLIENT_SECRET". The client secret never goes into a browser or a mobile app.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi…",
  "refresh_token": "def50200a1b2…"
}

5. Call the API

curl https://www.balktalk.net/api/dev/v1/me -H "Authorization: Bearer ACCESS_TOKEN"

Refreshing a token

An access token lasts 1 h. You get a new one with the refresh token, without the member:

curl -X POST https://www.balktalk.net/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "client_id": "YOUR_CLIENT_ID", "refresh_token": "REFRESH_TOKEN"}'

Every refresh returns a new pair of tokens. The old refresh token stops working at once, so always store the new one. A refresh token is valid for 60 days from its last use.

When access ends

The public API then returns 401 with "error": "invalid_token". This happens when:

  • the member removes access in Settings → Connected apps;
  • the member deletes their account or is suspended;
  • the app is suspended;
  • the token expires and the refresh fails.

Then delete the data of that member you do not have to keep and, if they want to continue, send them to the consent screen again.

Redirect addresses

  • https://… on your domain.
  • http://localhost or http://127.0.0.1 with any port, only while developing.
  • A mobile app: your own scheme in reverse-domain form, for example com.example.game:/login.
  • At most 5 addresses. An address must match to the last character, without #.

Sign-in errors

Errors of the consent screen and the token endpoint use the standard OAuth shape:

{ "error": "invalid_grant", "error_description": "…", "message": "…" }
error When
invalid_client unknown client_id, wrong client secret, or a suspended app
invalid_grant the code expired or was used, wrong code_verifier, redirect_uri does not match, the refresh token is not valid
invalid_scope unknown scope
access_denied the member denied (arrives at the redirect address)

If your app asks for a scope you have not declared in the portal, or it is in development and the member is not a tester, the member sees a page with an explanation and does not return to your address.

Strictly necessary cookies keep the site running. With your consent we also use optional ones (e.g. analytics) - you can change your choice at any time. Cookie Policy

Strictly necessary cookies keep the site running. With your consent we also use optional ones (e.g. analytics) - you can change your choice at any time. Cookie Policy

Strictly necessary

Always active

The site cannot work without them: sign-in, security, language and your choices. No consent needed and never used for tracking.

  • bt_session cookie · 30 days

    Session: keeps you signed in while you use the site.

    BalkTalk

  • XSRF-TOKEN cookie · 30 days

    Protects forms against forged requests (CSRF).

    BalkTalk

  • remember_web_* cookie · 13 months

    "Remember me": keeps you signed in after closing the browser.

    BalkTalk

  • bt_locale cookie · 12 months

    The language you chose.

    BalkTalk

  • bt_2fa_device cookie · 30 days

    Two-step sign-in: this device does not ask for a code for 30 days (when you choose "Remember this device").

    BalkTalk

  • bt_consent cookie · 12 months

    Your cookie choice (so we do not ask again).

    BalkTalk

  • bt-*, bt:* localStorage · until you clear it

    Browser local storage: theme, language, radio station, recent emoji, chat layout, hidden hints.

    BalkTalk

  • bt_invite cookie · 30 days

    Who invited you to BalkTalk (invite link) – so you both get a reward once you become an active member.

    BalkTalk

  • Cloudflare Turnstile service

    Human check on sign-up (challenges.cloudflare.com) - protects the site from fake accounts.

    Cloudflare, Inc. · Privacy policy

Third-party content

When you open it

Videos, music, GIFs, radio and the map come from other companies' servers. When you open them, those servers see your IP address and may set their own cookies.

  • Google Identity Services service

    One-click sign-in with the Google account you use in the browser ("Continue as …", accounts.google.com). Google sees that you visited the site; we get your name and email only when you click "Continue". Google may set the g_state cookie to remember that you closed the prompt.

    Google Ireland Ltd. · Privacy policy

  • YouTube service

    Videos in the blog and chat (youtube-nocookie.com).

    Google Ireland Ltd. · Privacy policy

  • Deezer service

    Song previews and covers on profiles, the Network and in chat.

    Deezer S.A. · Privacy policy

  • KLIPY service

    GIFs in chat and comments.

    KLIPY Inc. · Privacy policy

  • Radio stations service

    Live stream when you start the radio.

    The selected station's server

  • OpenStreetMap service

    Map in the Nearby module (only with separate map consent).

    OpenStreetMap Foundation · Privacy policy

  • OneSignal service

    Push notifications on this device – loaded only after you turn them on in Settings.

    OneSignal, Inc. · Privacy policy

Analytics

Anonymous visit statistics that help us improve the site. Only with your consent.

  • Google Analytics service

    Visit statistics (which pages are opened, where visitors come from, device) - no ads. Loaded only with your consent.

    Google Ireland Ltd. · Privacy policy

  • _ga cookie · 24 months

    Google Analytics: tells visitors apart (random number, no name or email).

    Google Ireland Ltd. · Privacy policy

  • _ga_0QPMP1EXWV cookie · 24 months

    Google Analytics: remembers the current visit.

    Google Ireland Ltd. · Privacy policy