Authorization ​

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 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 (except for getFreeList) must contain an API key.

2. API key can be specified as a query parameter, for example:

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

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

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

OAuth 2.0 ​

The OAuth 2.0 authorization protocol provides several authorization scenarios, in our case Authorization Code and Implicit Flow types are available.

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 Onlinesim;

• 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 ​

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 and password. 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:

Parameter Description ​

4. As a result of a successful request to https://onlinesim.io/oauth/token, you get JSON in response, 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 and the refresh_token is used to renew the access token when it expires.

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 ​

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 ​

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