Client OAuth authorization

To use client OAuth authentication it must be enabled in the app settings

During app creation you will need to indicate a redirect_uri to be used during OAuth authorization:

TypeDescriptionExample
Android SDKokauth://ok{app_id}
replace [app_id] with if of yours app
okauth://ok123456
iOS SDKok{app_id}://authorize
replace [app_id] with if of yours app
ok123456://authorize
ExternalUri which will process the authorization.
You can use https://api.ok.ru/blank.html
http://localhost/auth

1. Opening an OAuth authorization dialogue

To begin the authorization process you’ll need to open a new browser window (or WebView) and redirect user to a specially generated URL:

https://connect.ok.ru/oauth/authorize?client_id={clientId}&scope={scope}&response_type={{response_type}}&redirect_uri={redirectUri}&layout={layout}&state={state}

NameRequiredDescription
client_idYesApplication ID
scopeYesThe requested app permissions are separated by the “;” symbol. See app permissions
response_typeYesType of server response, enter token
redirect_uriYesURI to be redirected with access_token
The part of the URI following the “?” (query) is not included in the check. Regardless, we recommend that you use the state parameter to transfer dynamically changing data.
layoutYesHow the authorization window looks:
* w – (by default) the standard window for the full version of the site;
* m – the window for mobile authorization;
* a – the simplified window for mobile authorization without a header.
stateYesCondition parameter. Will be passed to redirect_uri whithout changes. Making it possible to transfer arbitrary data between different OAuth phases and protect against xsrf.

2. Allowing access permissions

If the user has already granted all specified permissions, the window closes automatically, and additional confirmation from the user is not required.

After jumping over to the generated URL, the user should enter his/her username and password unless that has already been done. After logging onto the site, he/she will be offered to authorize the app and confirm the requested permissions:

3. Getting access_token

After confirming authorization, the user will be redirected to the redirect_uri indicated when opening the authorization dialogue. At which point the access_token and session_secret_key parameters will be transferred after the # sign in addition to the state parameter if it was indicated at step 1:

{redirect_uri}#access_token={access_token}&session_secret_key={session_secret_key}&state={state}&permissions_granted={permissions_granted}&expires_in={expires_in}

NameDescription
access_tokenThe access token is used to make a request to the API
session_secret_keyThe secret session key used to sign the request to the API
stateThe value that was passed in the state parameter when opening the authentication dialog
permissions_grantedPermissions which the user has issued the application
expires_inAccess token lifetime in seconds

If there is an error or authorization refusal, an error parameter identifying the reason for the error is transferred:

{redirect_uri}#error={error}&state={state}

Possible errors

ErrorPossible reason
invalid_request* wrong code was passed
(error description - Invalid code)
* code has expired
(error description - Expired code)
* redirect_uri differs from the transmited in OAuth
(error description - Wrong redirect_uri)
invalid_client* could not find application by id
(error description - Unknown client)
unauthorized_client* invalid app secret key
(error description - Invalid request parameters)
access_denied* user isn’t authorized app
(e.g., it was removed in settings, error description - Access denied)
* refesh_token has expired
(error description - Refresh token expired)
* the user force logout from all devices
(see settings, error description - Logout all)
invalid_grant* can’t recognize grant_type parameter
(error description - Invalid grant type or Invalid parameters for grant type)
invalid_token* can’t define user
(error description - Session expired)
* refresh_token is invalid
(error description - Invalid refresh token / Invalid refresh token structure / Invalid refresh token, user not found)