====== RADIUSdesk API Permanent Users ======
===== Introduction =====
  * A Permanent User in RADIUSdesk has the following reference ids to other entities.
        * **user_id** This is the id of the owner (Access Provider) to which the Permanent User belong.
        * **realm_id** Each Permanent User has to belong to a Realm. A Realm is like a group but used by RADIUS.
        * **profile_id** Each Permanent User have to a Profile. A Profile can be used by RADIUS to dictate the service (bandwidth, amount of data available etc) a Permanent User will get when connecting to the Internet.
  * So to recap, **BEFORE** you can create a Permanent User **MAKE SURE** you have the following items since they are compulsory:
        * An Owner
        * A Realm
        * A Profile
  * This will be important when we want to use the API to create a Permanent User which is why we cover it first.

===== Adding A New Permanent User =====
==== API URL ====
  * We assume the FQDN of the RADIUSdesk server is hotspot.radiusdesk.com. Please adapt accordingly.
  * http://hotspot.radiusdesk.com/cake3/rd_cake/permanent-users/add.json

==== Items included in the POST ====
  * The following is  the **minimum** items than needs to be included in the POST request.
<code javascript>
{
    "user_id":0,
    "username":"demo2",
    "password":"demopassword",
    "realm_id":1,
    "profile_id":1,
    "token":"b4c6ac81-8c7c-4802-b50a-0a6380555b50"
}
</code>

  * Lets discuss these items listed.

^ Item      ^ Typical Value       ^ Comment          ^
| user_id  | 0     | The special value of 0 (Zero) will make the owner of the token the owner of the Permanent User.    |
| username  | demo2  | Unique username. Can even be an email address. See discussion about the suffix later in this document.  |
| password  | demopassword     | Password for user. No restrictions is placed on the length.  |
| realm_id    | 1     | The ID of the Realm the user should belong to.   | 
| profile_id    | 1    | The ID of the Profile the user should belong to.   |
| token    | b4c6ac81-8c7c-4802-b50a-0a6380555b50   | The API token of the user who initiate the API call  |

==== Finding the detail of the items ====
=== API Key ===

  * Each Access Provider (including the **root** user) in RADIUSdesk has a unique security token associated with them referred to as the API Key. This token changes each time the Access Provider password is changed.
  * An Access Provider can see their own API Key.
     * Log into RADIUSdesk
     * At the top right, click the menu button and select **Settings**.
{{:2021:api_key1.png?nolink|}}
  * An Access Provider can see any of the Access Providers under it by going to the Access Providers applet and edit a selected Access Provider. There will be a read-only field with the API Key for the selected Access Provider.
{{:2021:api_key2.png?nolink|}}

=== Realm ===
  * The list of Realms are shown by calling this URL (Be sure to replace the token with your API Key)
  * http://hotspot.radiusdesk.com/cake3/rd_cake/realms/index-ap-create.json?token=b4c6ac81-8c7c-4802-b50a-0a6380555b50
  * If there are a large amount of Realms on the system you may have to add pager items to the URL but this beyond the scope of this document.
  * Here is a sample reply
<code javascript>
{
    "items": [
        {
            "id": 1,
            "name": "demo1"
        }
    ],
    "success": true
}
  * We can either use **realm_id = 1** or **realm = demo1** when calling the API. The back-end is smart enough to convert the Realm name to to the Realm ID when adding the user.
</code>

=== Profile ===
  * The list of Profiles are shown by calling this URL (Be sure to replace the token with your API Key)
  * http://hotspot.radiusdesk.com/cake3/rd_cake/profiles/index-ap.json?token=b4c6ac81-8c7c-4802-b50a-0a6380555b50
  * If there are a large amount of Profiles on the system you may have to add pager items to the URL but this beyond the scope of this document.
  * Here is a sample reply
<code javascript>
{
    "items": [
        {
            "id": 1,
            "name": "demo1",
            "data_cap_in_profile": false,
            "time_cap_in_profile": false
        }
    ],
    "success": true
}
</code>
   * We can either use **profile_id = 1** or **profile = demo1** when calling the API. The back-end is smart enough to convert the Profile name to to the Profile ID when adding the user.

==== Alternative items to include in the POST ====
  * The following is  the **minimum** items (as an alternative based on the info above) than needs to be included in the POST request.
<code javascript>
{
    "user_id":0,
    "username":"demo2",
    "password":"demopassword",
    "realm":"demo1",
    "profile":"demo1",
    "token":"b4c6ac81-8c7c-4802-b50a-0a6380555b50"
}
</code>

==== Reply from the server to the  POST ====
  * If the request was successful the server will reply with the following
<code javascript>
{
  "success": true,
  "data": {
    "user_id": 44,
    "username": "demo2@demo1",
    "password": "demopassword",
    "realm": "demo1",
    "profile": "demo1",
    "token": "",
    "language_id": "_",
    "country_id": "4",
    "realm_id": 1,
    "profile_id": 1,
    "active": 1
  }
}
</code>

===== Adding a suffix to the username =====
  * You might have noticed that we specified the username as **demo2** but the name that was created has a **@demo1** added.
  * This is because of a setting we specified in the Realm we used.
  * See the following screenshot
{{:2021:realm_suffix.png?nolink|}}
  * Go ahead and remove the check for Permanent Users, save it and run the API call again.
  * The **@demo** should now be missing in the username.

===== Items allowed in the API =====
  * This section will list all the additional items that can be contained in the API call when adding a Permanent User.
  * The only compulsory ones are those discussed earlier in the document.

==== Personal Info ====

^ Item      ^ Typical Value       ^ Comment          ^
| name  |John    |varchar(50)  |
| surname  |Smith  |varchar(50)  |
| phone    |+27-724952041     |varchar(50)  | 
| language    | 4_4    | This is the only option available for now  |
| email    | john@radiusdesk.com   |varchar(100)  |
| address    | 25Main Road Henley On Klip   |varchar(255)  |

==== Activate & Expire ====
^ Item      ^ Typical Value       ^ Comment          ^
| from_date  |10/02/2021    |Month/Day/Year for  2 October 2021 use with **to_date** |
| to_date  |10/02/2022  |Month/Day/Year for 2 October 2021 use with **from_date** |

  * If these items are not specified, the account will be always active.

==== Optional Items ====
^ Item      ^ Typical Value       ^ Comment          ^
| static_ip  |192.168.31.2    |This value will be send inside the RADIUS Access Accept in the form of **Framed-IP-Address = 192.168.31.2** and **Service-Type = Framed-User** |
| extra_name  |POPI-Act |varchar(100) available for your own use /convention |
| extra_value  |Yes  |varchar(100) available for your own use /convention |