Схемы безопасности

APIKey

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


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

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

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

  1. Все запросы к API OnlineSIM должны содержать API ключ.

  2. API ключ можно указать как параметр запроса:

    Например:

       https://onlinesim.io/api/getNumbersStats.php?apikey={{api_key}}
    
  3. API ключ можно указать в заголовке запроса, используя схему Authorization: Bearer

    Например (Postman запрос):

       Authorization: Bearer {{key}}
       User-Agent: PostmanRuntime/7.29.2
       Accept: */\*
       Cache-Control: no-cache
       Postman-Token: 948bc880-8d25-4298-994f-fe6e22ada339
       Host: onlinesim.io
       Accept-Encoding: gzip, deflate, br
       Connection: keep-alive
       Cookie: xxxx
    

Данный способ представляет упрощенную авторизацию. Мы рекомендуем использовать OAuth 2.0 для более безопасной работы с данными.

apiKey
В: query
Query name: apikey

OAuth2

OAUTH 2.0

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

OAuth 2.0

OAuth 2.0. Authorization Сode Flow

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


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

Create a client

  1. Нажмите "Create". Добавленное Вами приложение будет отображаться в списке клиентов.

Token list

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

Авторизация пользователя и получение токена:
  1. Для авторизации пользователя нужно сделать GET запрос к https://onlinesim.io/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.io/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.io/oauth/authorize пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе OnlineSIM. Для этого ему необходимо будет нажать кнопку Authorize:

OAuth запрос

  1. В случае успешной авторизации пользователь будет перенаправлен по адресу redirect_uri с параметром code. Теперь Вы можете получить access token, для этого необходимо сделать POST запрос к https://onlinesim.io/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.io/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);

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


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

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

  1. В результате успешного выполнения запроса к https://onlinesim.io/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.io/oauth/token:

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

$response = $http->post('https://onlinesim.io/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

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

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

Создание клиента для OAuth

  1. Нажать "Create". Добавленное Вами приложение будет отображаться в списке клиентов.

Список токенов

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

Авторизация пользователя и получение токена:
  1. Для авторизации пользователя нужно сделать GET запрос к https://onlinesim.io/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.io/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.io/oauth/authorize, пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе OnlineSIM. Для этого ему необходимо будет нажать кнопку Authorize:

OAuth запрос

  1. В случае успешной авторизации пользователь будет перенаправлен по адрес redirect_uri с параметром access_token. Это и есть необходимый токен для авторизации в API OnlineSIM.

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

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

{
  "response": "ERROR_WRONG_KEY"
}
oauth2

implicit

URL авторизации: https://onlinesim.io/oauth/authorize
URL обновления: https://onlinesim.io//oauth/token
Области:
  • sms-scope
    Allows to access single-service activations API
  • rent-scope
    Allows to access rent API
  • proxy-scope
    Allows to access proxy API
  • free-scope
    Allows to access free numbers API

authorizationCode

URL авторизации: https://onlinesim.io/oauth/authorize
URL токена: https://onlinesim.io/oauth/token
Области:
  • sms-scope
    Allows to access single-service activations API
  • rent-scope
    Allows to access rent API
  • proxy-scope
    Allows to access proxy API
  • free-scope
    Allows to access free numbers API