Авторизация


Общая информация

Для работы с нашим API Ваше приложение должно быть авторизовано Вашим пользователем. Для этого мы предоставляем несколько способов авторизации: APIKEY, OAUTH 2.0 (Authorization code flow) и OAUTH 2.0 (Implicit flow). Вы можете выбрать любой наиболее удобный для Вас.

1. APIKEY

Api-key - cекретный ключ, используемый для упрощенной авторизации в API OnlineSIM.


Как получить apikey:

  1. Авторизоваться в личном кабинете, перейти во вкладку «Профиль пользователя».
  2. Ключ будет указан в строке "Api key". Его необходимо скопировать и добавить в Ваше приложение.

Как использовать:

  1. Все запросы к API OnlineSIM должны содержать Api-key.
  2. Api-key можно указать как параметр запроса: !!!<<добавить пример запроса с апикей в параметре>>.
  3. Api-key можно указать в заголовоке запроса: !!!<<добавить пример запроса с апикей в заголовке>>.

Данный способ представляет упрощенную авторизацию. По возможности следует использовать Oauth 2.0 для более безопасной работы с Вашими данными.

2. OAUTH 2.0

Протокол авторизации Oauth 2.0 поддерживает несолько видов авторизации. Для работы с нашим API предпочтительней использовать сценарии Authorization code или Implicit.

OAuth 2.0. Authorization code flow

{info} В данном сценарии все строится вокруг кода авторизации, который служит промежуточным звеном между вашим приложением и пользователем нашего сервиса. Вместо прямого запроса на авторизацию, Ваше приложение будет перенаправлять пользователя в наш сервис авторизации, где он сможет авторизовать Ваше приложение для работы с его данными.


Регистрация приложения в нашем сервисе авторизации:

  1. Перейти на странице oauth, при необходимости авторизоваться.
  2. Создать новое приложение, для этого нужно нажать "Create New Client".
  3. В открывшемся окне необходимо заполнить обязательные поля:
    • Name - название приложения или любое другое название, которое Вы будете ассоциировать со своим приложением;
    • Redirect URL - после авторизации пользователя в нашем сервисе авторизации, на данный URL будет перенаправлен клиент и отправлен код авторизации. Например, https://client.example.com/redirect;
    • Confidential - требуется ли для доступа секретный ключ.
step 1_2
  1. Нажимаем "Create".

    step 1
  2. Client ID и Secret нужно добавить в Ваше приложение. Они понадобятся для авторизации.


Авторизация пользователя и получение токена:

  1. Для авторизации пользователя нужно сделать GET запрос к конечной точке https://onlinesim.ru/oauth/authorize с параметрами client_id, redirect_uri, response_type, scope, state:


session()->put('state', $state = Str::random(40));
$query = http_build_query([
  'client_id' => $client_id,
  'redirect_uri' => 'https://client.example.com/redirect',
  'response_type' => 'code',
  'scope' => 'sms-scope rent-scope',
  'state' => $state,
]);
return redirect("https://onlinesim.ru/oauth/authorize?".$query);

Описание параметров

Название параметра Тип данных Описание
client_id STRING Client ID, который был получен при регистрации приложения
redirect_uri STRING Адрес на который будет перенаправлен клиент, после успешной авторизации, должен совпадать с Redirect URL при добавлении приложения.
response_type STRING Указать "code"
scope STRING Права доступа, разрешение на которые запрашивает ваше приложение у пользователя. Возможные варианты: sms-scope, rent-scope, proxy-scope, free-scope. Можно указать несколько
state STRING Значение состоящее из случайного набора символов, сервис авторизации вернет при обратном вызове. Рекомендуется использовать для предотвращения подделки межсайтовых запросов

Scopes:

  • sms-scope - доступ к API и управлению номерами на приеме onlineSIM;
  • rent-scope - доступ к API и аренде новых сим-карт от лица пользователя onlineSIM;
  • proxy-scope - доступ к API и управлению прокси пользователя onlineSIM;
  • free-scope - доступ к API и управлению бесплатными номерами;
  1. После после запроса к https://onlinesim.ru/oauth/authorize пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и в случае успеха авторизовать ваше приложение для работы с даными пользователя в сервисе onlineSIM. Для этого необходимо нажать кнопку Authorize:
step 2
  1. В случае успешной авторизации пользователь будет перенаправлен по адрес redirect_uri с параметром code, теперь вы можете получить access token, для этого необходимо сделать POST запрос к конечной точке https://onlinesim.ru/oauth/token:


$state = session()->pull('state');

if(strlen($state) > 0 && $state !== $request->get('state')) {  throw new InvalidArgumentException(); }

$http = new GuzzleHttp\Client([  'verify' => false ]);

$response = $http->post('https://onlinesim.ru/oauth/token', [  'form_params' => [   'grant_type' => 'authorization_code',   'client_id' => $client_id,   'client_secret' => $client_secret,   'redirect_uri' => 'https://client.example.com/redirect',   'code' => $request->code,  ] ]);

return json_decode((string) $response->getBody(), true);

{info} на этом этапе вы можете проверить параметр state, для подтверждения безопасного взаимодействия с сервисом авторизации


Описание параметров

Название параметра Тип данных Описание
grant_type STRING Сценарий авторизации, указать "authorization_code"
client_id STRING Client ID, который был получен при регистрации приложения
client_secret STRING Сlient_secret, который был получен при регистрации приложения
redirect_uri STRING Сдрес на который будет перенаправлен клиент, после успешной авторизации, должен совпадать с Redirect URL при добавлении приложения
code STRING Код авторизации, который был получен на предыдущем этапе

{info} так как client_secret - это приватный ключ, поэтому не рекомендуется его хранить в фронтенде клиента. Для более безопасного сценария необходимо хранить его в бэкэнде Вашего приложения. Для реализации сценария с авторизационным нужно передать полученны код фронтендем в бэкэнд Вашего сервиса, а уже он обратится в авторизационный сервис для получения токена.

  1. В результате успешного выполнения запроса к https://onlinesim.ru/oauth/token в ответ получите JSON, содержащий атрибуты access_token, refresh_token и expires_in. Атрибут expires_in содержит количество секунд до истечения срока действия токена доступа.

Авторизация запросов к API onlimeSIM и обновление токена:

Во все запросы к API нужно добавлять заголовок Authorization: Bearer access_token. Если в ответ на ваш запрос пришел ERROR_WRONG_KEY, Вам необходимо обновить токен или получить новый.

{ "response": "ERROR_WRONG_KEY" }

Для обновление токена необходимо сделать POST запрос к https://onlinesim.ru/oauth/token :


$http = new GuzzleHttp\Client([
  'verify' => false
]);
$response = $http->post('https://onlinesim.ru/oauth/token', [
 'form_params' => [
  'grant_type' => 'refresh_token',
  'client_id' => $client_id,
  'client_secret' => $client_secret,
  'refresh_token' => $refresh_token,
  'scope' => '',
 ],
]);
return json_decode((string) $response->getBody(), true);

Описание параметров

Название параметра Тип данных Описание
grant_type STRING Необходимо указать "refresh_token"
client_id STRING Client ID, который был получен при регистрации приложения
client_secret STRING Client_secret, который был получен при регистрации приложения
refresh_token STRING Refresh_token был получен вместе с access_token. Имеет гораздо большее время жизни и используется для обновления access_token
code STRING Код, который вы получили на предыдущем этапе

OAuth 2.0. Implicit flow

{info} Данный сценарий похож на сценарий c получением авторизационного кода, за исключением того, что вместо кода в redirect_uri сервис авторизации сразу отдает токен. Это удобно для приложений, которые не могут обеспечить приватность client_secret (десктопные приложения,мобильные прижения без серверной части и т.п.).

Регистрация приложения в нашем сервисе авторизации:

  1. Перейти на странице oauth, при необходимости авторизоваться.
  2. Создать новое приложение, для этого нужно нажать "Create New Client".
  3. В открывшемся окне необходимо заполнить обязательные поля:
    • Name - название приложения или любое другое название, которое Вы будете ассоциировать со своим приложением;
    • Redirect URL - после авторизации пользователя в нашем сервисе авторизации, на данный URL будет перенаправлен клиент и отправлен код авторизации. Например, https://client.example.com/redirect;
    • Confidential - требуется ли для доступа секретный ключ.
step 1_2
  1. Нажимаем "Create".

    step 1
  2. Client ID нужно добавить в Ваше приложение. Оно понадобится для авторизации.


Авторизация пользователя и получение токена:

  1. Для авторизации пользователя нужно сделать GET запрос к конечной точке https://onlinesim.ru/oauth/authorize с параметрами client_id, redirect_uri, response_type, scope, state:


session()->put('state', $state = Str::random(40));
$query = http_build_query([
  'client_id' => $client_id,
  'redirect_uri' => 'https://client.example.com/redirect',
  'response_type' => 'token',
  'scope' => 'sms-scope rent-scope',
  'state' => $state,
]);
return redirect("https://onlinesim.ru/oauth/authorize?".$query);

Описание параметров

Название параметра Тип данных Описание
client_id STRING Client ID, который был получен при регистрации приложения
redirect_uri STRING Адрес на который будет перенаправлен клиент, после успешной авторизации, должен совпадать с Redirect URL при добавлении приложения.
response_type STRING Указать "token"
scope STRING Права доступа, разрешение на которые запрашивает ваше приложение у пользователя. Возможные варианты: sms-scope, rent-scope, proxy-scope, free-scope. Можно указать несколько
state STRING Значение состоящее из случайного набора символов, сервис авторизации вернет при обратном вызове. Рекомендуется использовать для предотвращения подделки межсайтовых запросов

Scopes:

  • sms-scope - доступ к API и управлению номерами на приеме onlineSIM;
  • rent-scope - доступ к API и аренде новых сим-карт от лица пользователя onlineSIM;
  • proxy-scope - доступ к API и управлению прокси пользователя onlineSIM;
  • free-scope - доступ к API и управлению бесплатными номерами;
  1. После после запроса к https://onlinesim.ru/oauth/authorize пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и в случае успеха авторизовать ваше приложение для работы с даными пользователя в сервисе onlineSIM. Для этого необходимо нажать кнопку Authorize:
step 2
  1. В случае успешной авторизации пользователь будет перенаправлен по адрес redirect_uri с параметром access_token. Это и есть необходимый токен для авторизации в API OnlineSIM.

Авторизация запросов к API onlimeSIM:

Во все запросы к API нужно добавлять заголовок Authorization: Bearer access_token. Если в ответ на ваш запрос пришел ERROR_WRONG_KEY, Вам необходимо получить новый токен.

{ "response": "ERROR_WRONG_KEY" }