Server OAuth authorization

1. Opening an OAuth authorization dialogue

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

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}

Name	Required	Description
client_id	Yes	Application ID
scope	Yes	The requested app permissions are separated by the “;” symbol. See app permissions
response_type	Yes	Type of server response, enter code
redirect_uri	Yes	URI 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.
layout	Yes	How 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.
state	Yes	Condition parameter. Will be passed to redirect_uri without 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}

Name	Description
code	The authorization code received during step 3
client_id	Application ID
client_secret	Application secret key
redirect_uri	The URI redirect indicated in step 1
grant_type	Type 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;
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}

Name	Description
refresh_token	The refresh token received during step 4
client_id	Application id
client_secret	Application secret key
grant_type	Type of granted rights, pass refresh_token

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

Possible errors

Error	Possible 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)