Adrese
| Šta | Adresa |
|---|---|
| Ekran pristanka | https://www.balktalk.net/oauth/authorize |
| Tokeni | https://www.balktalk.net/oauth/token |
| Javni API | https://www.balktalk.net/api/dev/v1 |
1. Napravi PKCE par
Za svaku prijavu napravi nasumičan code_verifier (43 do 128 znakova) i njegov izazov code_challenge = base64url(SHA-256(verifier)). Verifier čuvaš kod sebe, izazov šalješ.
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 je obavezan za aplikacije bez tajnog ključa. Preporučujemo ga i uz tajni ključ.
2. Pošalji člana na ekran pristanka
https://www.balktalk.net/oauth/authorize
?response_type=code
&client_id=TVOJ_CLIENT_ID
&redirect_uri=https://tvoj-sajt.example/callback
&scope=identity scores
&state=NASUMICNA_VRIJEDNOST
&code_challenge=IZAZOV
&code_challenge_method=S256
| Parametar | Značenje |
|---|---|
client_id |
Client ID iz portala |
redirect_uri |
Povratna adresa, tačno kako je upisana u portalu |
scope |
Dozvole odvojene razmakom. identity se uvijek podrazumijeva |
state |
Tvoja nasumična vrijednost. Kad se član vrati, provjeri da je ista |
code_challenge |
PKCE izazov iz prvog koraka |
Član koji nije prijavljen prvo se prijavi na BalkTalk. Zatim vidi ekran pristanka sa nazivom i ikonom tvoje aplikacije i spiskom dozvola. Ako je iste dozvole već odobrio, ekran se preskače.
3. Član se vraća sa kodom
Kad odobri:
https://tvoj-sajt.example/callback?code=KOD&state=NASUMICNA_VRIJEDNOST
Kad odbije:
https://tvoj-sajt.example/callback?error=access_denied&state=NASUMICNA_VRIJEDNOST
Kod važi 10 minuta i može se iskoristiti jednom.
4. Zamijeni kod za token
Aplikacija bez tajnog ključa:
curl -X POST https://www.balktalk.net/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"client_id": "TVOJ_CLIENT_ID",
"redirect_uri": "https://tvoj-sajt.example/callback",
"code": "KOD",
"code_verifier": "VERIFIER"
}'
Aplikacija sa serverom dodaje "client_secret": "TAJNI_KLJUC". Tajni ključ nikad ne ide u preglednik ni u aplikaciju za telefon.
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1Qi…",
"refresh_token": "def50200a1b2…"
}
5. Zovi API
curl https://www.balktalk.net/api/dev/v1/me -H "Authorization: Bearer ACCESS_TOKEN"
Obnova tokena
Token pristupa traje 1 h. Novi dobijaš tokenom za obnovu, bez člana:
curl -X POST https://www.balktalk.net/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type": "refresh_token", "client_id": "TVOJ_CLIENT_ID", "refresh_token": "REFRESH_TOKEN"}'
Svaka obnova vraća nov par tokena. Stari token za obnovu odmah prestaje važiti, pa uvijek sačuvaj novi. Token za obnovu važi 60 dana od zadnje upotrebe.
Kad pristup prestane
Javni API tada vraća 401 sa "error": "invalid_token". To se desi kad:
- član ukine pristup u Postavke → Povezane aplikacije;
- član obriše račun ili bude suspendovan;
- aplikacija bude suspendovana;
- token istekne, a obnova ne uspije.
Tada obriši podatke tog člana koje ne moraš čuvati i, ako želi dalje, pošalji ga ponovo na ekran pristanka.
Povratne adrese
https://…na tvom domenu.http://localhostilihttp://127.0.0.1sa bilo kojim portom, samo dok razvijaš.- Aplikacija za telefon: tvoja šema u obliku obrnutog domena, npr.
com.primjer.igra:/prijava. - Najviše 5 adresa. Adresa mora biti ista do zadnjeg znaka, bez
#.
Greške prijave
Greške ekrana pristanka i tokena su u standardnom OAuth obliku:
{ "error": "invalid_grant", "error_description": "…", "message": "…" }
error |
Kada |
|---|---|
invalid_client |
nepoznat client_id, pogrešan tajni ključ ili suspendovana aplikacija |
invalid_grant |
kod je istekao ili iskorišten, pogrešan code_verifier, redirect_uri se ne poklapa, token za obnovu ne važi |
invalid_scope |
nepoznata dozvola |
access_denied |
član je odbio (stiže na povratnu adresu) |
Ako tvoja aplikacija traži dozvolu koju nisi prijavio u portalu, ili je u razvoju a član nije tester, član vidi stranicu sa objašnjenjem i ne vraća se na tvoju adresu.