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

---

How to get an API key:

1. Log in to personal account, go to the 'User Profile' and click on "API" tab.
2. Copy the key from the API Key field and add it to your application.

---

How to use it:

1. All OnlineSIM API requests must contain an API key.

2. API key can be specified as a query parameter

   For example:

      https://onlinesim.io/api/getNumbersStats.php?apikey={{api_key}}
   

3. API key can be also specified in the request header (using Authorization: Bearer schema)

   For example (Postman request):

      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
   

This is a simplified authorization, please use OAuth 2.0 for better data security if possible.

OAUTH 2.0

The OAuth 2.0 authorization protocol provides several grant types. In our case Authorization Code and Implicit Scripts types are available.

OAuth 2.0. Authorization code flow

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. Open OAuth page, log in if necessary.
2. Add your app by clicking "Create New Client".
3. In the next window, fill in the required fields:
   • Name - could be the app name or any other name you and your users will associate with the app;
   • Redirect URL: after user authorization on our server, the client will be redirected with authorization code to this URL. For example, https://client.example.com/redirect;
   • Confidential: shows whether a secret key is required for access.

4. Click "Create". New client will appear in the list of applications.

5. Client ID and Secret will be used in your app for authorization.

---

Authorize a user and get a token:

1. To authorize a user, make a GET request to 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);

---

Parameter Description

Parameter Name	Data Type	Description
client_id	STRING	Client ID (returned when the app registration process is complete)
redirect_uri	STRING	Redirect destination for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process.
response_type	STRING	Use code as a value
scope	STRING	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	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 receiving;
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 is sent, 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, he has to click on 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 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);

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	Grant type, use authorization_code as a value
client_id	STRING	Client ID (returned when the app registration process is complete)
client_secret	STRING	Client_secret (returned when the app registration process is complete)
redirect_uri	STRING	Redirect destination for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process.
code	STRING	Authorization code, obtained in the previous step

Since client_secret is a private key, it is not recommended to store it in the frontend of the client. For better security, you should store it in the backend of your app. To implement the Authorization Code scenario, you need to pass this code from the frontend to the backend of your service.

4. As a result of a successful request 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 and token refreshment:

For all API requests, add the Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you need to refresh your token or get a new one.

{
  "response": "ERROR_WRONG_KEY"
}

To refresh the token you must make a POST request to 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);

---

Parameter Description

Parameter name	Data type	Description
grant_type	STRING	Grant type, use refresh_token as a value
client_id	STRING	Client ID (returned when the app registration process is complete)
client_secret	STRING	Client_secret (returned when the app registration process is complete)
refresh_token	STRING	Refresh_token is obtained along with the access_token. It has a much longer lifetime and is used to refresh access_token
code	STRING	Authorization code, obtained in the previous step

OAuth 2.0. Implicit flow

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 OAuth page, 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 - could be the app name or any other name you and your users will associate with the 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.

4. Press "Create". New client will appear in the list of applications.

5. Client ID will be used in your app for 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' => 'token',
            'scope' => 'sms-scope rent-scope',
            'state' => $state,
]);

return redirect("https://onlinesim.io/oauth/authorize?".$query);

---

Parameter Description

Parameter name	Data type	Description
client_id	STRING	Client ID (returned when the app registration process is complete)
redirect_uri	STRING	Redirect destination for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process.
response_type	STRING	Use token as a value
scope	STRING	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	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 receiving;
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 https://onlinesim.io/oauth/authorize is sent, 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, he has to click on Authorize button:

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 to all API requests Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you should get a new token.

{
  "response": "ERROR_WRONG_KEY"
}