Documentation
If you wish to use a UI design compatible with the official Seznam brand, you are free to download the official "S" image and the corresponding design manual.
The following sign-in flow works according to the https://tools.ietf.org/html/rfc6749 (OAuth 2.0). All URLs used as a redirect_uri
are transformed to https, excluding the localhost
hostname. Relevant methods:
User redirection
The first step is to redirect the user to the login form. This can happen in multiple ways, including a regular HTTP redirection, link-based navigation, opening a new browser tab or a pop-up window via JavaScript.
The scope
query string parameter defines one or more words (comma-separated) that specify user data to be provided to the third party. There is a dedicated page describing these scopes and their purpose.
GET https://login.szn.cz/api/v1/oauth/auth
?client_id=...
&scope=identity
&response_type=code
&redirect_uri=https://...
&state=...
An optional claims
query string parameter can be used to specify which requested scopes are optional (default) and which are mandatory. This parameter uses a relatively complex syntax – see the relevant specification. For instance, if we decided that the adulthood scope is to be mandatory, we would include the following JSON object (properly serialized and url-encoded) in the claims
parameter:
{
"userinfo": {
"adulthood": {
"essential": true
}
}
}
Converting the code to token
A successful authorization results in a redirection to the address ${redirect_uri}?code=...
; it is now necessary to perform a server-side HTTP request to exchange the received one-time code
for an authorization token and user data.
POST https://login.szn.cz/api/v1/oauth/token
Accept: application/json
{
"grant_type": "authorization_code",
"code": "..."
"redirect_uri": "...",
"client_secret": "...",
"client_id": "..."
}
The response object contains standard RFC data and also:
oauth_user_id
is a unique persistent user identifier; more specific user data can be retrieved via further calls (token-authorized)account_name
contains a human-readable label for the accountscopes
contains a list of scopes authorized by the user
User data
GET https://login.szn.cz/api/v1/user
Authorization: bearer ...token...
Accept: application/json
The response object's shape depends on the set of scopes requested by the third party (provided those were authorized by the user). Read more about that at the scopes documentation.
Token revocation
It is possible to revoke either the normal access token (token_type_hint=access_token
) or the long-term refresh token (token_type_hint=refresh_token
).
POST https://login.szn.cz/api/v1/oauth/revoke
Authorization: bearer ...token...
Accept: application/json
{
"token_type_hint": "refresh_token" | "access_token",
"token": "..."
}
Service icon
This image will be displayed in the user's Account page (next to the list of active sessions). It must have a square aspect ratio and will be rendered 32×32 pixels large.