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:
|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 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:
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:
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:
|code||The authorization code received during step 3|
|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 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 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:
|refresh_token||The refresh token received during step 4|
|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.
|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)