Management Portals

You can use REST API calls to obtain information about management portals, to create or edit management portals, and to delete management portals.

The following table lists the properties that can be used in the body of a management portal-related request and/or are provided in the response body. (In the "Optional" column, if a default value is applicable, it is listed in angle brackets (< >).)

Resource: Management Portal

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
guid String Yes orderBy, like Optional on create only, but not on any subsequent uses The unique identifier for this management portal.
name String Yes orderBy, like No The display name for this management portal; must be unique.
description String Yes orderBy, like Yes A description for this management portal.
accessSecret String Yes orderBy, like No The access secret that is used to log into this portal by an approved email address.

links

self, properties, users, controlConfiguration, uiConfiguration

 Link No orderBy, like- Yes

This includes the following href links that can be used in other API calls:

  • self-referencing link
  • link to the controlConfiguration resource
  • link to the uiConfguration resource
  • link to the list of properties associated with this management portal.
  • link to the list of users associated with this management portal.

Resource: ControlConfiguration

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
createUnit Boolean No Yes No Indicates if the user is allowed to create a unit on this property.
deleteUnit boolean No Yes No Indicates if the user is allowed to delete a unit on this property
basicUnitProperties boolean No Yes No Indicates if the user is allowed to alter the basic unit properties. This includes the name, description, and contact information for all units in the properties included in the management portal.
changeUnitSecrets boolean No Yes No Indicates if the user is allowed to reset the wi-fi secret and guest wi-fi secret on the unit.
resetUnitAuthToken boolean No Yes No Indicates if the user is allowed to set the unit state to "TOKEN_RESET", thereby resetting the tenant portal authentication token on the unit.
alterUnitState boolean No Yes No Indicates if the user is allowed to change the basic state of the unit between ACTIVE/SUSPENDED.
setHelpText boolean No Yes No Indicates if the user is allowed to set the help text for the tenant portal displayed for this property.
setAnnouncements boolean No Yes No Indicates if the user is allowed to set the announcements for the tenant portal displayed for this property. .
links Link No orderBy, like Yes Self referencing link and link to the parent management portal.

Resource: UiConfiguration

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
title String Yes No Yes The title to use in the management portal UI.
subtitle String Yes No Yes The subtitle to use in the management portal UI.
loginText String Yes No Yes Text to display when logging in to the management portal UI.
mainColor String Yes No Yes The main color is used for the main header and any buttons or links. White text will be used on top of this color.
accentColor String Yes No Yes The accent color is used for sub-headers and borders.
separatorColor String Yes No Yes The separator color is used for lines in between rows of data.
textColor String Yes No Yes The text color is the default text color used to display information throughout the portal.
logoFileName String NO No Yes The name of the logo file, if one has been uploaded. This will be updated when the logo file is changed via the logo file link.
iconFileName String NO No Yes The name of the icon file, if one has been uploaded. This will be updated when the icon file is changed via the icon file link.
links         logoFile, favicon, self, and parent (management portal)

Management Portal URIs and Actions

The following table indicates the URIs that you can append to the root URI, along with the actions you can take, and possible return codes you can receive.

Management Portal URIs and Actions

URI Action Description Return Codes
/mgmtPortals GET Returns the list of management portals that are in the Cloudpath system.

401 - Unauthorized

200 - OK

POST Creates a management portal. Will return a conflict if the secret exists on another management portal defined in this account or if the name exists for another management portal defined in this account.

409 - Conflict

401 - Unauthorized

201 - Created

/mgmtPortals/{guid} GET Returns information about the specified management portal.

404 - Not Found

401 - Unauthorized

200 - OK

DELETE Deletes the management portal specified and all its associated data.

401 - Unauthorized

204 - No content

200 - OK

PUT Updates details about the management portal.

404 - Not Found

401 - Unauthorized

200 - OK

/mgmtPortals/{guid}/properties GET Returns the list of properties assigned to this management portal. Supports all of the sorting and filtering as defined by "property" in the core Cloudpath APIs.
will provide xref

404 - Not Found

401 - Unauthorized

200 - OK

/mgmtPortals/{guid}/properties/{propertyGuid} PUT

Adds a property to the list of properties that are assigned to the specified management portal. This has no impact on the property itself.

404 - Not Found

401 - Unauthorized

200 - OK

DELETE Removes a property from the list of properties that have been assigned to the specified management portal. This has no impact on the property itself.

401 - Unauthorized

204 - No content

200 - OK

/mgmtPortals/{guid}/controlConfiguration GET

Returns the control configuration information for the specified management portal. The control configuration specifies which APIs are accessible to users of this portal.

404 - Not Found

401 - Unauthorized

200 - OK

PUT Updates the control configuration information for the specified management portal.

404 - Not Found

401 - Unauthorized

200 - OK

/mgmtPortals/{guid}/uiConfiguration

GET

Returns the UI configuration information for the specified management portal.

404 - Not Found

401 - Unauthorized

200 - OK

PUT Updates the UI configuration information for the specified management portal.

404 - Not Found

401 - Unauthorized

200 - OK

/mgmtPortals/{guid}/uiConfiguration/logoFile POST This method allows the user to post an image file that will be used for the management portal. Note that the media type in the headers of the POST must be Multipart Form Data. A null file can also be be set if there is no desire for a logo file. If the file name is null, the logo file will be set to null regardless of the data in the form. If the form data is bad, a 422 message is thrown.

422 - Unprocessable Entity

404 - Not Found

401 - Unauthorized

200 - OK

/mgmtPortals/{guid}/uiConfiguration/favicon POST This method allows the user to post an icon file that will be used for the management portal. Note that the media type in the headers of the POST must be Multipart Form Data. A null file can also be be set if there is no desire for an icon file. If the file name is null, the icon file will be set to null regardless of the data in the form. If the form data is bad, a 422 message is thrown.

422 - Unprocessable Entity

404 - Not Found

401 - Unauthorized

200 - OK

Example of Using GET for Management Portals

This example demonstrates how to obtain a listing of all management portals that have already been created in the Cloudpath UI.

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/publicApi/mgmtPortals

where https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).

Request Headers:

The following table shows the required request headers for this URI example, with an example value of an active token that must be pasted into the Authorization header value:

Request Headers

Key Value
Content-type application/json
Authorization eyJhbGciOiJIUzUxMiJ9.eyJhY2NvdW50UGsiOiIxIiwicm9sZVBrIjoiMjAwMDAiLCJhdWQiOiJSRVNUX0FQSSIsInN1YiI6IjEiLCJpc3MiOiJueEo5REV6aG1XUGJlSVZGaGR4Wm44cnh6aFhlR1AycmpOVHJxYndqSnhRPSIsImlhdCI6MTYyODg5MTkwMiwiZXhwIjoxNjI4ODkyMjAyfQ.yPA5OcUsfvkWtD298k-jvl-gCIE6fYEQ_dfl5mSAVYd5-iGsFEHwa_GTGOf4ahuKcPHVhhQCWOpoiUjL5uHEwg

Request Body:

None required.

Action:

Use the GET action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 200 OK" if the GET is successful. The response body provides information about all existing management portals in your Cloudpath system. In this example, "Lake View Apartments Management Portal" is the only existing management portal. The information in the response body will match the configuration of Lake View Apartments Management Portal as specified in the UI. Any values that were not specified in the UI are the default values: 

{
    "page": {
        "page": 1,
        "pageSize": 1,
        "totalCount": 1
    },
    "contents": [
        {
            "guid": "MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503",
            "name": "Lake View Apartments Management Portal",
            "description": "",
            "accessSecret": "secret",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "property",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "controlConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/controlConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "users",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/users?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Example of Using POST to Create a Management Portal

This example demonstrates how to create a new management portal in your Cloudpath system by using the REST API POST call.

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/publicApi/mgmtPortals

where https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).

Request Headers:

The following table shows the required request headers for this URI example, with an example value of an active token that must be pasted into the Authorization header value:

Request Headers

Key Value
Content-type application/json
Authorization eyJhbGciOiJIUzUxMiJ9.eyJhY2NvdW50UGsiOiIxIiwicm9sZVBrIjoiMjAwMDAiLCJhdWQiOiJSRVNUX0FQSSIsInN1YiI6IjEiLCJpc3MiOiJueEo5REV6aG1XUGJlSVZGaGR4Wm44cnh6aFhlR1AycmpOVHJxYndqSnhRPSIsImlhdCI6MTYyODg5MTkwMiwiZXhwIjoxNjI4ODkyMjAyfQ.yPA5OcUsfvkWtD298k-jvl-gCIE6fYEQ_dfl5mSAVYd5-iGsFEHwa_GTGOf4ahuKcPHVhhQCWOpoiUjL5uHEwg

Request Body:

The following is an example of a request body for creating a management portal. You can refer to the preceding Resource tables for a list and descriptions of properties you can use to define your management portal. For instance, in this example, a management portal called "Green Buildings Management Portal" is being created with the values provided in the body. 

{
"name": "Green Buildings Management Portal",
 "description": "Management portal for the Green Buildings Construction Group",
 "accessSecret": "secret22"        
}

Action:

Use the POST action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 201 Created" if the POST is successful. You can see that a "guid" (a unique identifier for the newly created management portal) is included in the response body. 

{
    "guid": "MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f",
    "name": "Green Buildings Management Portal",
    "description": "Management portal for the Green Buildings Construction Group",
    "accessSecret": "secret22",
    "links": [
        {
            "rel": "self",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "property",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f/properties?page=1&pageSize=10{&filter,orderBy}",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "uiConfiguration",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f/uiConfiguration",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "controlConfiguration",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f/controlConfiguration",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "users",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f/users?page=1&pageSize=10{&filter,orderBy}",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        }
    ]
}

Verifying the Newly Created Management Portal in the Cloudpath UI:

You can go to the Managed Access > Management Portal area of the UI to confirm that the portal was created correctly.

Example of Using PUT to Change Default Portal Controls of a Management Portal

This example demonstrates how to change the portal controls of a management portal in your Cloudpath system by using the REST API PUT call.

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f/controlConfiguration

where:

  • https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).
  • MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f is the GUID of the management portal.

Request Headers:

The following table shows the required request headers for this URI example, with an example value of an active token that must be pasted into the Authorization header value:

Request Headers

Key Value
Content-type application/json
Authorization eyJhbGciOiJIUzUxMiJ9.eyJhY2NvdW50UGsiOiIxIiwicm9sZVBrIjoiMjAwMDAiLCJhdWQiOiJSRVNUX0FQSSIsInN1YiI6IjEiLCJpc3MiOiJueEo5REV6aG1XUGJlSVZGaGR4Wm44cnh6aFhlR1AycmpOVHJxYndqSnhRPSIsImlhdCI6MTYyODg5MTkwMiwiZXhwIjoxNjI4ODkyMjAyfQ.yPA5OcUsfvkWtD298k-jvl-gCIE6fYEQ_dfl5mSAVYd5-iGsFEHwa_GTGOf4ahuKcPHVhhQCWOpoiUjL5uHEwg

Request Body:

The following is an example of a request body of a PUT request for portal controls. You can refer to the ControlConfiguration resource table earlier in this topic for a list and descriptions of properties you can change.

Note: Your request body must contain all portal control properties and the boolean value you desire for each one, even for properties whose values you wish to remain as currently configured.
For instance, in this example, you are setting only the portal controls deleteUnit and resetUnitAuthToken to true. 
{    "createUnit": false,
    "deleteUnit": true,
    "basicUnitProperties": false,
    "changeUnitSecrets": false,
    "resetUnitAuthToken": true,
    "alterUnitState": false,
    "setHelpText": false,
    "setAnnouncements": false}

Action:

Use the PUT action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 200 OK" if the PUT is successful. The reponse body below indicates that the request successfully set the values as specified.

{
    "createUnit": false,
    "deleteUnit": true,
    "basicUnitProperties": false,
    "changeUnitSecrets": false,
    "resetUnitAuthToken": true,
    "alterUnitState": false,
    "setHelpText": false,
    "setAnnouncements": false,
    "links": [
        {
            "rel": "self",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "mgmtPortal",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/mgmtPortals/MduPortalAccess-71891b0f-1b27-472a-8a9e-1fe21e21be1f",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        }
    ]
}

Verifying the Changes in the Management Portal in the Cloudpath UI:

You can go to the Managed Access > Management Portal area of the UI, then click the wrench icon for the portal, then view the "Portal Controls" properties in the Access Details tab to confirm that the changes took effect.

Parent topic: Management Portal APIs