Server OAuth authorization

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

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 code
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. Acquiring code

After confirming authorization, the user will be redirected to the redirect_uri indicated when opening the authorization dialogue, where the GET parameters will have the code transferred, in addition to the state if it was indicated at the 1 stage:

{redirect_uri}?code={code}&state={state}

The code parameter received is active for 2 minutes.

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}

4. Acquiring access_token

To receive an access_token, you will need to run a POST request from your site’s server to the API at URL:

https://api.ok.ru/oauth/token.do?code={code}&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&grant_type={grant_type}

NameDescription
codeThe authorization code received during step 3
client_idApplication ID
client_secretApplication secret key
redirect_uriThe URI redirect indicated in step 1
grant_typeType of granted rights, pass authorization_code

A json containing the requested access_token or information on the error will sent back from the server.

Type of answer if successful:

{
    "access_token": "{access_token}",
    "token_type": "session",
    "refresh_token": "{refresh_token}",
    "expires_in":"{expires_in}"
}
  • access_token – access token for requests to API
  • token_type – currently only the session is returned
  • refresh_token – the refresh token can be used in the future to simplify the authorization procedure, active for 30 days; non-refundable in the case of the token with extended lifetime (see LONG_ACCESS_TOKEN)
  • expires_in – the duration of the access token lifetime in seconds

Type of answer if error:

{
    "error": "{error}",
    "error_description": "{error_description}"
}
  • error – error code
  • error_description – error description

5. Using a refresh_token With a refresh_token you can obtain an access_token via the simplified procedure by sending one POST query to:

https://api.ok.ru/oauth/token.do?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type={grant_type}

NameDescription
refresh_tokenThe refresh token received during step 4
client_idApplication id
client_secretApplication secret key
grant_typeType of granted rights, pass refresh_token

The reply format is the same as acquiring access_token, just without a refresh_token.

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)