RMS API Credits: Difference between revisions
No edit summary |
|||
(16 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
__TOC__ | __TOC__ | ||
== 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=== | ||
Line 14: | Line 17: | ||
This can be done by going to your RMS Account settings and then the Security page. Any Authentication type (other than None) is viable. | 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.<br> [[File:RMS Settings Two Factor Authentication.png|none|thumb|950x950px|RMS Settings Two Factor Authentication]] | 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.<br> | ||
<br> | |||
[[File:RMS Settings Two Factor Authentication.png|none|thumb|950x950px|RMS Settings Two Factor Authentication]] | |||
<br> | |||
===Add new access token=== | ===Add new access token=== | ||
Line 20: | Line 28: | ||
Once there, simply press Add new access token. | Once there, simply press Add new access token. | ||
[[File:RMS API Add new access token.png|none|thumb|850x850px]] | |||
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: | 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: | ||
Line 27: | Line 36: | ||
* '''credit_transfer_codes:write''' | * '''credit_transfer_codes:write''' | ||
<br> | |||
[[File:RMS_API_Credits_-_read_-_transfer_codes_read_write.png|alt=|none|frame|Selected scopes for RMS API Credits]] | [[File:RMS_API_Credits_-_read_-_transfer_codes_read_write.png|alt=|none|frame|Selected scopes for RMS API Credits]] | ||
<br> | <br> | ||
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. | 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. | ||
[[File:RMS API Access Token Example.png|none | <br> | ||
[[File:RMS API Access Token Example.png|none|RMS API Access Token Example|alt=|thumb|500x500px]] | |||
<br> | |||
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''' | 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''' | ||
Line 39: | Line 51: | ||
==Using the API with Postman to gather information about credit balance== | ==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: | To get the general information about your current RMS credit balance, we can use the '''[https://developers.rms.teltonika-networks.com/pages/api.html#/credits/creditsSummary GET /credits/summary]''' endpoint: | ||
1. Select the GET option and input the endpoint URL into the necessary field - <nowiki>https://rms.teltonika-networks.com/api/credits/summary</nowiki>. | 1. Select the GET option and input the endpoint URL into the necessary field - <nowiki>https://rms.teltonika-networks.com/api/credits/summary</nowiki>. | ||
Line 55: | Line 67: | ||
4. Press Send. | 4. Press Send. | ||
[[File:Rms Api Wiki Credits Part 1.mp4|750px]] | |||
If everything was done correctly, you should get a response containing information about your credit balance. This includes: | If everything was done correctly, you should get a response containing information about your credit balance. This includes: | ||
Line 63: | Line 76: | ||
* 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. | * 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== | ==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: | To get general information about your RMS credit codes, you can use the '''[https://developers.rms.teltonika-networks.com/pages/api.html#/credits%20codes/creditsTokensAll GET /credits/codes]''' endpoint: | ||
1. Select the GET option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | 1. Select the GET option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | ||
Line 82: | Line 94: | ||
4. Press Send. | 4. Press Send. | ||
[[File:Rms Api Wiki Credits Part 2.mp4|750px]] | |||
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. | 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. | ||
Line 87: | Line 101: | ||
===Generate a new credit code=== | ===Generate a new credit code=== | ||
---- | ---- | ||
To generate a new credit code, you can use the '''POST /credits''/''codes''' endpoint: | To generate a new credit code, you can use the '''[https://developers.rms.teltonika-networks.com/pages/api.html#/credits%20codes/creditsTokensAdd POST /credits''/''codes]''' endpoint: | ||
1. Select the POST option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | 1. Select the POST option and input the endpoint URL into the necessary field – <nowiki>https://rms.teltonika-networks.com/api/credits/codes</nowiki>; | ||
Line 101: | Line 115: | ||
3. In the Body tab, input the necessary Request body (many POST requests require request bodies). For example: | 3. In the Body tab, input the necessary Request body (many POST requests require request bodies). For example: | ||
{ | { | ||
''"amount": 4, | |||
''"amount": 4, | "comment": "Some example comment", | ||
"company_id": 458'' | |||
"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. | * Amount – The number of credits you wish the credit code to contain. This cannot exceed the maximum credits that your RMS company currently owns. | ||
Line 116: | Line 126: | ||
4. Press Send. | 4. Press Send. | ||
[[File:Rms Api Wiki Credits Part 3.mp4|750px]] | |||
If everything was done correctly, you should receive a response containing the credit code, which can be used by anyone. | If everything was done correctly, you should receive a response containing the credit code, which can be used by anyone. |
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.