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

---

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

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

---

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

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

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

   Например:

      http://api-conserver.onlinesim.ru/stubs/handler_api.php?api_key={api_key}&action=getNumber&service=google&country=4
   

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

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

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

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

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

OAUTH 2.0

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

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.

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

4. Сохраните 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 (проверьте её после редиректа)

2. После запроса к https://onlinesim.io/oauth/authorize пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе Onlinesim. Для этого ему необходимо будет нажать кнопку Authorize:

3. В случае успешной авторизации пользователь будет перенаправлен по адресу redirect_uri с параметром code. Теперь Вы можете получить access token, для этого необходимо сделать POST запрос к https://onlinesim.io/oauth/token:

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

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

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

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

4. В результате успешного выполнения запроса к 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
code	STRING	Код авторизации, который Вы получили на предыдущем этапе

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 (проверьте её после редиректа)

2. После запроса к https://onlinesim.io/oauth/authorize, пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе Onlinesim. Для этого ему необходимо будет нажать кнопку Authorize:

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

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

---

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

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

{
  "response": "ERROR_WRONG_KEY"
}