Схемы безопасности
APIKey
Секретный ключ, используемый для упрощенной авторизации в API OnlineSIM.
Как получить API ключ:
- Авторизоваться в личном кабинете, перейти настройки профиля, выбрать вкладку "API".
- Ключ будет указан в строке
API key
. Его необходимо скопировать и добавить в Ваше приложение/программу.
Как использовать:
Все запросы к API OnlineSIM должны содержать API ключ.
API ключ можно указать как параметр запроса:
Например:
https://onlinesim.io/api/getNumbersStats.php?apikey={{api_key}}
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 для более безопасной работы с данными.
query
apikey
OAuth2
OAUTH 2.0
Протокол авторизации OAuth 2.0 поддерживает несколько видов авторизации. Для работы с нашим API можно использовать сценарии Authorization Code Flow или Implicit Flow.
OAuth 2.0. Authorization Сode Flow
В данном сценарии все строится вокруг кода авторизации, который служит промежуточным звеном между Вашим приложением и пользователем нашего сервиса. Вместо прямого запроса на авторизацию, Ваше приложение будет перенаправлять пользователя в наш сервис авторизации, где он сможет авторизовать Ваше приложение для работы с его данными.
Регистрация приложения в нашем сервисе авторизации:
- Перейти на страницу OAuth, при необходимости авторизоваться.
- Создать новое приложение, для этого нужно нажать "Create New Client".
- В открывшемся окне необходимо заполнить обязательные поля:
Name
- название приложения или любое другое название, которое Вы и Ваши пользователи будут ассоциировать с приложением;Redirect URL
- после авторизации пользователя в нашем сервисе авторизации, на данный URL будет перенаправлен клиент и отправлен код авторизации. Например,https://client.example.com/redirect
;Confidential
- требуется ли для доступа секретный ключ.
- Нажмите "Create". Добавленное Вами приложение будет отображаться в списке клиентов.
Client ID
иSecret
будут использоваться в Вашем приложении для авторизации.
Авторизация пользователя и получение токена:
- Для авторизации пользователя нужно сделать 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 и управлению бесплатными номерами;
- После запроса к https://onlinesim.io/oauth/authorize пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе OnlineSIM. Для этого ему необходимо будет нажать кнопку
Authorize
:
- В случае успешной авторизации пользователь будет перенаправлен по адресу
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
- это приватный ключ, поэтому не рекомендуется его хранить в фронтенде клиента. Для большей безопасности необходимо хранить его в бэкенде Вашего приложения. Для реализации сценария с авторизационным кодом нужно передать полученный код фронтендем в бэкэнд Вашего сервиса, а уже он должен обратится в авторизационный сервис для получения токена.
- В результате успешного выполнения запроса к 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
(десктопные приложения, мобильные приложения без серверной части и т.п.).
Регистрация приложения в нашем сервисе авторизации:
- Перейти на страницу OAuth, при необходимости авторизоваться.
- Создать новое приложение, для этого нужно нажать "Create New Client".
- В открывшемся окне необходимо заполнить обязательные поля:
Name
- название приложения или любое другое название, которое Вы и Ваши пользователи будут ассоциировать с приложением;Redirect URL
- после авторизации пользователя в нашем сервисе авторизации, на данный URL будет перенаправлен клиент и отправлен код авторизации. Например,https://client.example.com/redirect
;Confidential
- требуется ли для доступа секретный ключ.
- Нажать "Create". Добавленное Вами приложение будет отображаться в списке клиентов.
Client ID
будет использоваться в Вашем приложении для авторизации.
Авторизация пользователя и получение токена:
- Для авторизации пользователя нужно сделать 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 и управлению бесплатными номерами;
- После запроса к https://onlinesim.io/oauth/authorize, пользователь из Вашего приложения будет перенаправлен на страницу авторизации, где ему необходимо указать логин пароль и, в случае успеха, авторизовать Ваше приложение для работы с данными пользователя в сервисе OnlineSIM. Для этого ему необходимо будет нажать кнопку
Authorize
:
- В случае успешной авторизации пользователь будет перенаправлен по адрес
redirect_uri
с параметромaccess_token
. Это и есть необходимый токен для авторизации в API OnlineSIM.
Авторизация запросов к API onlineSIM:
Во все запросы к API нужно добавлять заголовок Authorization: Bearer access_token
.
Если в ответ на ваш запрос пришел ERROR_WRONG_KEY
, Вам необходимо получить новый токен.
{
"response": "ERROR_WRONG_KEY"
}
implicit
https://onlinesim.io/oauth/authorize
https://onlinesim.io//oauth/token
sms-scope
Allows to access single-service activations APIrent-scope
Allows to access rent APIproxy-scope
Allows to access proxy APIfree-scope
Allows to access free numbers API
authorizationCode
https://onlinesim.io/oauth/authorize
https://onlinesim.io/oauth/token
sms-scope
Allows to access single-service activations APIrent-scope
Allows to access rent APIproxy-scope
Allows to access proxy APIfree-scope
Allows to access free numbers API