Spis treści

Tokeny

Tokeny są alternatywną metodą logowania się do zasobów Grona, nie wymagającą przechowywania zestawu ciasteczek. Po pozyskaniu tokena, wysyłamy go razem z każdym requestem, jako kolejny parametr w POST lub GET. Mają one pierwszeństwo nad ciasteczkami sesji - jeśli w requeście jest zarówno sesja jak i tokeny, sesja nie jest brana pod uwagę.

	uzyskanie tokena
url	api.grono.net/pub/token/issue/
metoda	GET lub POST
parametry	format=FORMAT
dane	jak przy logowaniu się, czyli login, password, client, cliver,lang oraz domain - zobacz niżej
zwraca	200 OK + token 400 Bad Request 403 Forbidden

Jeśli podamy parametr format, odpowiedź zawiera klucz "token", którego wartością jest nowy token, oraz klucz "handle", który jest identyfikatorem użytkownika do dalszych zapytań, tak jak w logowaniu się. W przeciwnym wypadku, obie te wartości oddzielone są dwukropkiem, czyli treść ma postać token:handle.

Domeny

Tokeny mają ograniczony zakres zasobów na które obowiązują. Określa to wybrana domena (parametr domain). Token nie nadaje się do używania zasobów z innej domeny, niż ta na którą został wydany. Nie istnieje możliwość przeniesienia go do innej domeny, ani dodania mu kolejnych.

nazwa	zasoby	ważność
gallery	Galerie, Avatar, NajnowszeFotki	10 minut
contacts	Znajomi	10 minut
messages	Wiadomości, Kartki	10 minut
forum	Forum	10 minut
profile	Profil, Blimp	30 minut

Ważność i odświeżanie

Tokeny mają ograniczony czas ważności, wykazany w tabelce wyżej. Aplikacja musi umieć odnawiać tokeny. Użycie w zapytaniu nieistniejącego lub nieważnego tokena spowoduje wygenerowanie statusu 403, tak jakby użytkownik się nie zalogował. Ważność tokenu liczona jest od momentu wystawienia.

Ilość tokenów

Istnieje ograniczenie na ilość aktywnych tokenów w danym momencie wydanych jednemu użytkownikowi. Na chwilę obecną wynosi ono 10. Jeśli aplikacja potrzebuje więcej tokenów, musi poczekać aż wygasną, lub unieważnić token.

Unieważnianie

	unieważnienie tokena
url	api.grono.net/pub/token/revoke/
metoda	GET lub POST
dane	token=TOKEN
zwraca	200 OK + token 400 Bad Request 404 Not Found

Unieważnienie tokena powoduje, że nie nadaje się już do autoryzowania requestów, niezależnie od tego kto się nim posługuje. W połączeniu z faktem, że tokeny są ważniejsze od sesji, daje to pewien stopień zabezpieczenia przed kradzieżą tokenów. Uwaga: aby unieważnić token, nie trzeba być zalogowanym, ani posiadać ważnego tokena.