Authorization

• General Information
• 1. APIKEY
• 2. OAUTH 2.0
  • Authorization code
  • Implicit

General Information

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.

1. APIKEY

Api-key is a secret key for a simplified authorization in OnlineSIM API.

How to get an Api-key:

1. log in at personal account, go to the User Profile tab.
2. The key is listed in the Api key line. Copy it and add it to your app.

How to use it:

1. All OnlineSIM API requests must contain an Api-key.
2. Api-key can be specified as a query parameter: !!!<<add a sample query with an Api-key in the parameter.
3. The Api-key can be specified in the request header: !!!<<add a sample query with an Api-key in the header.

This’s a simplified authorization. Possibly use Oauth 2.0 for better data security.

2. OAUTH 2.0

The Oauth 2.0 authorization protocol supports several authorization ways. To work with our API, using the Authorization Code or Implicit Scripts is preferable.

OAuth 2.0. Authorization code flow

{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.

Register the app in our authorization service:

1. Go to open oauth page, log in if necessary.
2. Create a new app by clicking "Create New Client".
3. In the next window, fill in the required fields:
   • Name is the *app name or another name associated with your app;
   • Redirect URL: after user authorization in our authorization service, the client will be redirected to this URL, and an authorization code will be sent. For example, https://client.example.com/redirect;
   • Confidential shows * whether a secret key is required to access.

4. Press Create.

   

5. Client ID and Secret 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 ``https://onlinesim.io/oauth/authorize``` with parameters 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);

Description of parameters

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;

2. After the request to `https://onlinesim.io/oauth/authorize``, the user from your app will be redirected 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:

3. If the authorization is successful, the user will be redirected to redirect_uri with the parameter code, now you can get the access token after making a POST request to the endpoint 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);

{info} at this point, you can check the state parameter, to confirm secure communication with the authorization service

Parameter Description

{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.

4. As a result of a successful query to ``https://onlinesim.io/oauth/token```, you get JSON in reply, which contains access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds before the access token is expired.

Authorization of requests to onlineSIM API and token update:

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([
&nbsp;&nbsp;'client_id' => $client_id,
&nbsp;&nbsp;'redirect_uri' => 'https://client.example.com/redirect',
&nbsp;&nbsp;'response_type' => 'token',
&nbsp;&nbsp;'scope' => 'sms-scope rent-scope',
&nbsp;&nbsp;'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" }