Авторизация

api_key

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

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

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

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

  1. Все запросы к текущему API Onlinesim (за исключением getFreeList) должны содержать API ключ.

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

       https://onlinesim.io/api/getTariffs.php?api_key={api_key}
Property Value
Тип apiKey
В query
Название api_key
BearerAuth

API ключ также можно использовать для авторизации в заголовке запроса, используя схему Authorization: Bearer, например:

Authorization: Bearer {api_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
Property Value
Тип http
Схема bearer
OAuth2

OAuth 2.0

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

Authorization URL: https://onlinesim.io/oauth/authorize

Token URL: https://onlinesim.io/oauth/token

Scopes:

  • sms-scope открывает доступ к управлению номерами для услуги "Прием SMS" от Onlinesim;
  • rent-scope открывает доступ к аренде виртуальных телефонных номеров Onlinesim;
  • free-scope открывает доступ к использованию бесплатных номеров Onlinesim.

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

  1. Перейдите на страницу OAuth

  2. Создайте новый клиент, указав:

    • Name - название приложения или любое другое название, которое Вы и Ваши пользователи будут ассоциировать с приложением;
    • Redirect URL - URL, на который будет перенаправлен клиент после авторизации и куда будет направлен код авторизации приложения;
    • Confidential - необзятально, отметье клиент как Confidential, если ваше приложение работает на сервере и может безопасно хранить Client Secret.

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

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

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

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

OAuth 2.0. Authorization Сode Flow

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

  1. Авторизуйте клиент через GET запрос к https://onlinesim.io/oauth/authorize с параметрами client_id, redirect_uri, response_type, scope, state:
Описание параметров
Название параметра Тип данных Описание
client_id STRING Client ID, который был получен после регистрации приложения
redirect_uri STRING Адрес на который будет перенаправлен клиент, после успешной авторизации, должен совпадать с Redirect URL, который Вы указали при регистрации приложения.
response_type STRING Указать code
scope STRING Права доступа, разрешение на которые запрашивает Ваше приложение у пользователя. Возможные варианты: sms-scope, rent-scope, free-scope. Можно указать несколько значений
state STRING Случайная строка для защиты от CSRF (проверьте её после редиректа)
  1. После запроса к https://onlinesim.io/oauth/authorize пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе Onlinesim. Для этого ему необходимо будет нажать кнопку Authorize:

OAuth запрос

  1. В случае успешной авторизации пользователь будет перенаправлен по адресу redirect_uri с параметром code. Теперь Вы можете получить access token, для этого необходимо сделать POST запрос к https://onlinesim.io/oauth/token:
Описание параметров
Название параметра Тип данных Описание
grant_type STRING Сценарий авторизации, для сценария Authorization Сode необходимо указать authorization_code
client_id STRING Client ID, который был получен после регистрации приложения
client_secret STRING Сlient_secret, который был получен после регистрации приложения
redirect_uri STRING Адрес на который будет перенаправлен клиент, после успешной авторизации, должен совпадать с Redirect URL, который Вы указали при регистрации приложения
code STRING Код авторизации, который был получен на предыдущем этапе
  1. В результате успешного выполнения запроса к https://onlinesim.io/oauth/token, в ответ получите JSON, содержащий поля access_token, refresh_token и expires_in. Поле expires_in определяет количество секунд до истечения срока действия токена доступа, refresh_token используется для обновления токена доступа при истечении его срока действия.

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

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

{
  "response": "ERROR_WRONG_KEY"
}

Для обновления токена необходимо сделать POST запрос к https://onlinesim.io/oauth/token с параметрами grant_type, client_id, client_secret и refresh_token. Для поля refresh_token необходимо использовать значение, которое было получено в шаге 4.

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

OAuth 2.0. Implicit flow

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

  1. Авторизуйте клиент через GET запрос к https://onlinesim.io/oauth/authorize с параметрами client_id, redirect_uri, response_type, scope, state:
Описание параметров
Название параметра Тип данных Описание
client_id STRING Client ID, который был получен при регистрации приложения
redirect_uri STRING Адрес на который будет перенаправлен клиент, после успешной авторизации, должен совпадать с Redirect URL, который Вы указали при добавлении приложения.
response_type STRING Используйте token в качестве значения
scope STRING Права доступа, разрешение на которые запрашивает Ваше приложение у пользователя. Возможные варианты: sms-scope, rent-scope, free-scope. Можно указать несколько значений
state STRING Случайная строка для защиты от CSRF (проверьте её после редиректа)
  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"
}
Property Value
Тип oauth2

OAuth Flows

implicit

  • URL авторизации: https://onlinesim.io/oauth/authorize
  • URL обновления: https://onlinesim.io/oauth/token

  • Области:

    • sms-scope: grants access to manage numbers for the SMS receiving service from Onlinesim
    • rent-scope: grants access to renting phone numbers from Onlinesim
    • free-scope: grants access to using Onlinesim free numbers

authorizationCode

  • URL авторизации: https://onlinesim.io/oauth/authorize
  • URL токена: https://onlinesim.io/oauth/token

  • Области:

    • sms-scope: grants access to manage numbers for the SMS receiving service from Onlinesim
    • rent-scope: grants access to renting phone numbers from Onlinesim
    • free-scope: grants access to using Onlinesim free numbers