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.
2. Send the member to the consent screen
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://localhostorhttp://127.0.0.1with 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.