To work with our API, your app should be authorized by your user. There are several authorization ways we can provide: APIKEY, OAUTH 2.0 (Authorization code flow) and OAUTH 2.0 (Implicit flow). You can select the most convenient one.
Api-key is a secret key for a simplified authorization in OnlineSIM API.
This’s a simplified authorization. Possibly use Oauth 2.0 for better data security.
The Oauth 2.0 authorization protocol supports several authorization ways. To work with our API, using the Authorization Code or Implicit Scripts is preferable.
{info} This scenario is based on the authorization code, operating as an intermediate link between your app and the user of our service. Instead of a direct authorization request, your app will redirect the user to our authorization service to authorize your app for working with the user’s data.
https://client.example.com/redirect
;Press Create.
Client ID and Secret must be added to your app for further authorization.
Description of parameters
Parameter Name | Data Type | Description |
---|---|---|
client_id | STRING | is a Client ID to obtain when the app is registered |
redirect_uri | STRING | is an address to redirect the client after a successful authorization, it must match the Redirect URL when adding the app. |
response_type | STRING | Specify "code" |
scope | STRING | are access rights that your app asks from the user. Possible values: sms-scope, rent-scope, proxy-scope, free-scope. You can specify several of them |
state | STRING | is a value consisting of a random character set, the authorization service will return when called back. It’s recommended to use to prevent forging cross-site requests |
Scopes:
- sms-scope enables the access to the API and number management on onlineSIM reception;
- rent-scope enables the access to the API and new SIM cards leasing on behalf of the onlineSIM user;
- proxy-scope enables the access to the API and onlineSIM user’s proxy management of the;
- free-scope enables the access to the API and managing free numbers;
https://onlinesim.io/oauth/token
:{info} at this point, you can check the state parameter, to confirm secure communication with the authorization service
Parameter Description
Parameter name | Data type | Description |
---|---|---|
grant_type | STRING | authorization script, specify "authorization_code" |
client_id | STRING | Client ID, which was obtained when registering the app |
client_secret | STRING | Client_secret, which was obtained during the app registration |
redirect_uri | STRING | is an address to redirect the client after a successful authorization, it must match the Redirect URL when adding the app |
code | STRING | authorization code, obtained in the previous step |
{info} as client_secret is a private key, so it is not recommended to store it in the frontend of the client. For a more secure scenario, you should store it in the backend of your app. To implement the authorization scenario, you need to pass the received code from the frontend to the backend of your service, and already it will contact the authorization service to get the token.
For all API requests, add the Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you need to update your token or get a new one. ``json.line-numbers { "response": "ERROR_WRONG_KEY" }
To update the token you must make a POST request to ``{ url('/oauth/token') }}`` :
@printCode(php)
$http = new GuzzleHttp\Client([
'verify' => false
]);
$response = $http->post('{{url('/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);
@endPrintCode
> Parameter Description
Parameter name | Data type | Description
-------------- | -------------- | -------------- | -------------- |
grant_type | STRING | it is necessary to specify "refresh_token"
client_id | STRING | Client ID, which was obtained when registering the app
client_secret | STRING | client_secret, which was obtained during app registration
refresh_token | STRING | Refresh_token was obtained along with the access_token. It has a much longer lifetime and is used to refresh access_token
code | STRING | the code you received in the previous step
<a name="IMPLICIT"></a>
### OAuth 2.0. Implicit flow
> {info} This scenario is similar to the one for getting the authorization code, except that instead of the code in redirect_uri, the authorization service immediately gives the token. This is useful for apps that cannot ensure client_secret privacy (desktop apps, mobile apps without a server part, etc.).
#### **Register the app in our authorization service:**
1. Go to the <a href="{{url('/oauth')}}" target="_block">open oauth page</a>, log in if necessary.
2. Create a new app by clicking "Create New Client".
3. In the window that opens, you must fill in the required fields:
* Name is the *app name or any other name you will associate with your app;
Redirect URL: *after user authorization in our authorization service, the client will be redirected to this URL, and the authorization code will be sent. For example, `https://client.example.com/redirect`*;
Confidential shows * whether a secret key is required for access.
<div class="text-center" style="text-align: center;">
<img src="/assets/oauth/step1_2.png" style="width: 100%;" alt="step 1_2">
</div>
4. Press "Create".
<div class="text-center" style="text-align: center;">
<img src="/assets/oauth/step1.png" style="width: 100%;" alt="step 1">
</div>
5. Client ID must be added to your app for further authorization.
---
#### **Authorize a user and get a token:**
1. To authorize a user, make a GET request to the endpoint ``{{ url('/oauth/authorize') }}``` with parameters *client_id*, *redirect_uri*, *response_type*, *scope*, *state*:
@printCode(php)
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("{{url('/oauth/authorize')}}?".$query);
@endPrintCode
>Description of parameters
Parameter name | Data type | Description
-------------- | -------------- | -------------- | -------------- |
client_id | STRING | Client ID, obtained when registering the app
redirect_uri | STRING | is an address to redirect the client after a successful authorization, it must match the Redirect URL when adding the app.
response_type | STRING | Specify "token"
scope | STRING | are access rights that your app asks from the user. Possible values: sms-scope, rent-scope, proxy-scope, free-scope. You can specify several of them
state | STRING | value consisting of a random set of characters, the authorization service will return when called back. It is recommended to use to prevent forging cross-site requests
>Scopes:
* sms-scope enables the access to the API and number management on onlineSIM reception;
* rent-scope enables the access to the API and new SIM cards leasing on behalf of the onlineSIM user;
* proxy-scope enables the access to the API and proxy management of the onlineSIM user;
* free-scope enables the access to the API and management of free numbers;
2. After the request to `{{{ url('/oauth/authorize') }}``, the user will be redirected from your app to the authorization page to enter the login&password and, if successful, authorize your app to work with user data in the onlineSIM service. To do so, press the *Authorize* button:
<div class="text-center" style="text-align: center;">
<img src="/assets/oauth/step2.png" style="width: 100%;" alt="step 2">
</div>
3. In case of successful authorization, the user will be redirected to the redirect_uri address with the parameter *access_token*. This token is required for authorization in OnlineSIM API.
---
#### **Authorization of requests to the onlineSIM API:**
Add the Authorization to all API requests: Bearer *access_token* header.
If your request results in ERROR_WRONG_KEY, you should get a new token.
``json.line-numbers
{ "response": "ERROR_WRONG_KEY" }