Setting up an application
To use client OAuth authentication it must be enabled in the app settings.
During app creation you will need to specify a redirect_uri to be used during OAuth authorization:
| Type | Description | Example |
|---|---|---|
| Android SDK | okauth://ok{app_id} replace [app_id] with your app’s id | okauth://ok123456 |
| iOS SDK | ok{app_id}://authorize replace [app_id] with your app’s id | ok123456://authorize |
| External | Uri which will process the authorization. You can use https://oauth.mycdn.me/blank.html | http://localhost/auth |
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 token |
| 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. Getting access_token
After confirming an authorization, the user will be redirected to the redirect_uri specified during the authorization dialogue opening. At this point the access_token and session_secret_key parameters will be transferred after the # sign in addition to the state parameter if it was specified 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}
| Name | Description |
|---|---|
| access_token | The access token used to make a request to the API |
| session_secret_key | The secret session key used to sign the request to the API |
| state | The value that was passed in the state parameter when opening the authentication dialog |
| permissions_granted | Permissions which the user has issued to the application |
| expires_in | Access token’s 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
| 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) |