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:

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

Using an API key provides a simplified way to authorize requests. We recommend using OAuth 2.0 for more secure data handling.

The API key can also be used for authorization in the request header using the Authorization: Bearer scheme

For example (Postman request):

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

Using an API key provides a simplified way to authorize requests. We recommend using OAuth 2.0 for more secure data handling.

OAUTH 2.0

The OAuth 2.0 authorization protocol provides several authorization scenarios, in our case Authorization Code and Implicit Flow types are available. For detailed information about the OAuth 2.0 protocol and additional guidance, please refer to the official documentation.

Authorization URL: https://onlinesim.io/oauth/authorize

Token URL: https://onlinesim.io/oauth/token

Scopes:

**sms-scope** grants access to manage numbers for the "SMS Receiving" service from Onlinesim;
**rent-scope** grants access to renting phone numbers from an Onlinesim user;
**free-scope** grants access to using Onlinesim's free numbers.

Register the app in our authorization service:

1. Open OAuth page
2. Add your app by clicking "Create New Client", then fill the fields below:
   • 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.
   • Confidential - (optional), mark the client as Confidential if your application runs on a server and can securely store the Client Secret.

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

4. Save the Client ID and Secret in a secure location; they will be used by your application for authorization.

OAuth 2.0. Authorization code flow

Authorize a user and get a token:

1. Authorize a client with a GET request to https://onlinesim.io/oauth/authorize with parameters client_id, redirect_uri, response_type, scope, state:

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 value of Redirect URL field you've set 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, free-scope. You can specify multiple values
state	STRING	A random string for CSRF protection (verify it after the redirect)

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:

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 scenario type, use authorization_code when using the Authorization Code flow.
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 URL 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 with the parameters grant_type, client_id, client_secret, and refresh_token. For the refresh_token field, use the value obtained in step 4.

Parameter Description

Parameter name	Data type	Description
grant_type	STRING	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

OAuth 2.0. Implicit flow

Authorize a user and get a token:

1. Authorize a client with a GET request to the endpoint https://onlinesim.io/oauth/authorize with parameters client_id, redirect_uri, response_type, scope, state:

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, free-scope. You can specify multiple values
state	STRING	A random string for CSRF protection (verify it after the redirect)

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.

At this point, you can check the state parameter, to confirm secure communication with the authorization service

---

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"
}