RMS API Credits: Difference between revisions
No edit summary |
No edit summary |
||
(One intermediate revision by one other user not shown) | |||
Line 1: | Line 1: | ||
__TOC__ | __TOC__ | ||
==Using a | == Introduction == | ||
Using the RMS API allows users to automate tasks and integrate RMS into their own solutions. In this guide, an example will be provided which step-by-step shows a way to apply the RMS API to manage your RMS credit balance, as well as create a credit code used for transferring credits between different accounts. | |||
Such an application of the RMS API could be used in solutions where transferring credits is an automated process, not requiring any manual input. | |||
All documentation of the RMS API can be found here - https://developers.rms.teltonika-networks.com/ | |||
This example only includes using Personal Access Tokens to use the API. The RMS API also allows for Application Authentication, used specifically in applications that can use RMS as an OAuth provider. | |||
===Two-Factor Authentication=== | ===Two-Factor Authentication=== |
Latest revision as of 14:21, 15 April 2022
Introduction
Using the RMS API allows users to automate tasks and integrate RMS into their own solutions. In this guide, an example will be provided which step-by-step shows a way to apply the RMS API to manage your RMS credit balance, as well as create a credit code used for transferring credits between different accounts.
Such an application of the RMS API could be used in solutions where transferring credits is an automated process, not requiring any manual input.
All documentation of the RMS API can be found here - https://developers.rms.teltonika-networks.com/
This example only includes using Personal Access Tokens to use the API. The RMS API also allows for Application Authentication, used specifically in applications that can use RMS as an OAuth provider.
Two-Factor Authentication
Firstly, to create a Personal Access Token, your account must have Two-Factor Authentication enabled.
This can be done by going to your RMS Account settings and then the Security page. Any Authentication type (other than None) is viable.
Once Two-Factor authentication is enabled, you can then head over to the API → Access tokens page of your Account settings to begin creating a Personal Access token.
Add new access token
Once there, simply press Add new access token.
Next, input a name for this access token and select the necessary Scopes. Scopes are basically permissions – what the access token will be capable of doing in your account. For this example, we will be selecting these scopes:
- credits:read
- credit_transfer_codes:read
- credit_transfer_codes:write
These scopes will allow us to read information about our current credits and credit codes, as well as create new credit codes. After selecting the necessary scopes, press Save Personal Access Token – you will be shown a table containing your Personal Access Token. WARNING: This is the only time the created access token will be shown, make sure to copy it, as you will not be able to see it again.
Now that we have the access token, we can now use the RMS API. All information about each API endpoint can be found in the API reference
There are multiple ways to use an API, for this example, we will be using Postman.
Using the API with Postman to gather information about credit balance
To get the general information about your current RMS credit balance, we can use the GET /credits/summary endpoint:
1. Select the GET option and input the endpoint URL into the necessary field - https://rms.teltonika-networks.com/api/credits/summary.
2. Input your personal access token in either the Authorization tab or in your query parameters:
a. In the Authorization tab select Bearer token, then paste your access token in the Token field.
OR
b. In the Params tab, make a Key and Value pair: Key – Authorization; Value – Bearer YOUR_ACCESS_TOKEN.
3. (Optional) This endpoint has an optional parameter ‘company’ so you can input another parameter in the Params tab if you wish to filter the results by a specific company.
4. Press Send.
If everything was done correctly, you should get a response containing information about your credit balance. This includes:
- Remaining credits as well as the total amount you have had.
- Amount of devices currently being monitored. Monitored devices simply mean any devices that have the Monitoring switch enabled in RMS.
- Credit coverage – The date provided shows how long your currently owned amount of credits is enough for your current RMS setup. This takes into account the amount of devices and their credit configuration (Service and Auto Extend). The calculation also considers if you have any subsidiary RMS companies that have the “Use parent credits” option enabled.
Using the API with postman to manage RMS credit codes
To get general information about your RMS credit codes, you can use the GET /credits/codes endpoint:
1. Select the GET option and input the endpoint URL into the necessary field – https://rms.teltonika-networks.com/api/credits/codes;
2. Input your personal access token in either the Authorization tab, or in your query parameters:
a. In the Authorization tab select Bearer token, then paste your access token in the Token field;
OR
b. In the Params tab, make a Key and Value pair: Key – Authorization; Value – Bearer YOUR_ACCESS_TOKEN;
3. (Optional) This endpoint has multiple optional parameters so you can input another parameter in the Params tab if you wish to filter the results by a specific parameter.
4. Press Send.
If everything was done correctly, you should get a response containing a list of your credit codes and general information. This includes information such as the code itself, what company it has been used by (if it has been used), creation date, etc.
Generate a new credit code
To generate a new credit code, you can use the POST /credits/codes endpoint:
1. Select the POST option and input the endpoint URL into the necessary field – https://rms.teltonika-networks.com/api/credits/codes;
2. Input your personal access token in either the Authorization tab or in your query parameters:
a. In the Authorization tab select Bearer token, then paste your access token in the Token field;
OR
b. In the Params tab, make a Key and Value pair: Key – Authorization; Value – Bearer OUR_ACCESS_TOKEN;
3. In the Body tab, input the necessary Request body (many POST requests require request bodies). For example:
{ "amount": 4, "comment": "Some example comment", "company_id": 458 }
- Amount – The number of credits you wish the credit code to contain. This cannot exceed the maximum credits that your RMS company currently owns.
- Comment – A comment simply for your own management purposes. Can be left empty, if desired, i.e. “comment”: “”
- Company_id – The ID of the RMS company from which the credits will be taken to create the credit code. The ID can be found either by visiting the RMS web page or, if using the API, via the GET/companies endpoint. This ID does not change over time.
4. Press Send.
If everything was done correctly, you should receive a response containing the credit code, which can be used by anyone.