MAC Registrations

You can use REST API v2 calls to obtain information about existing MAC-registration lists and specific MAC registrations as well as to add a registration.

The following table lists the properties that can be used in the body of a MAC-registration 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: MacRegistration

Property Name Type Editable Filter/Sort Optional in Request/Response Body? Description
guid String No Neither Optional on create only, but not on any subsequent uses The unique identifier for this MAC registration.
macAddress String No sortBy, like No The MAC address for this registration. Must be provided on a POST, and may not be changed.
status Enum Yes sortBy, eq, in No Status of the registration, either ACTIVE, REVOKED or EXPIRED. If not provided, the status defaults to "Active". The status can only be set to REVOKED or ACTIVE. EXPIRED is dependent on the expired date of this registration.
username String No sortBy, like Yes A username for this device; it does not reflect an authenticated user that has gone through an actual authentication process.
email String No sortBy, like Yes The email address to associate with this device.
location String No sortBy, like Yes Location of the device.
deviceName String No sortBy, like Yes The device name assigned to this registration .
expirationDate String <date> Yes sortBy, like Yes The ISO 8601 date time that indicates when this registration expires. If not provided in the request body of a POST, this value defaults to 24 hours from the creation of this registration.
lastSeenDate String <date> No sortBy, like Yes The ISO 8601 date time that this MAC address was authenticated in Cloudpath. Will be ignored on POST but will always be returned.
revokeInfo RevokeInfo Yes See the "Resource: revokeInfo" table below. Yes if the status is chaned to REVOKED. Information about a revoke. A "Conflict" will occur if this property is not provided on a PUT/POST with a status of REVOKED.
links Links [] <array> No No Yes This includes the following href links that can be used in other API calls:
  • self: links for each registration within the registration list
  • parent: link to the registration list

Resource: revokeInfo

Property Name Type Editable Filter/Sort Optional in Request/Response Body? Description
date String <date> Yes sortBy, like No The ISO 8601 date time that this registration was revoked.
reason String No sortBy, like No The reason that the registration was revoked.
status Enum Yes sortBy, like No Status of the registration, either ACTIVE, REVOKED or EXPIRED. If not provided, the status defaults to "Active". The status can only be set to REVOKED or ACTIVE. EXPIRED is dependent on the expired date of this registration.

MAC Registration 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.

MAC Registration URIs and Actions

URI Action Description Return Codes
/registrationLists/{listGuid}/macRegistrations GET Returns the set of registrations assigned to this list.

401 - Unauthorized

200 - OK

404 - Not found
POST Adds a registration to this list. If the MAC address provided already exists, a new MAC registration will be created and the existing one will be revoked.

422 - Unprocessable Entity (invalid format)

404 - Not found

401 - Unauthorized

201 - Created

/registrationLists/{listGuid}/macRegistrations/{guid} GET Returns the specified registration that belongs to this list.

404 - Not Found

401 - Unauthorized

200 - OK

PUT Changes the properties in the specified MAC registration. You may change the status to ACTIVE or REVOKED, but EXPIRED is based on the expiration date. If REVOKED is requested, but no RevokeInfo is provided, a "422, Unprocessable Entity" response code is returned.

422 - Unprocessable entity

404 - Not found

401 - Unauthorized

200 - OK

Example of Using GET to Obtain Information About a Specific MAC-Registration List

This example demonstrates how to obtain information about a specific MAC-registration list in your Cloudpath system by using the REST API GET call.

URI:

This example uses the following URI: 

 https://Jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1/macRegistrations

where:

  • https://Jeff243.cloudpath.net/admin/apiv2 is the root URI of the Cloudpath system being used (must include https, as shown)
  • 5XcTc6SjkHDL is an example of an API key generated from the Configuration > API Keys section of the Cloudpath UI
  • WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1 is the GUID of the MAC registration list. This GUID can be found by doing a GET request on all the registration lists in the Cloudpath system. For more information, refer to Registration Lists URIs and Actions.

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 eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqZWZmLnJob2RpZUBjb21tc2NvcGUuY29tIiwicm9sZVBrIjoiMjEwMDAiLCJhY2NvdW50QWRtaW5QayI6IjIiLCJhcGlLZXkiOiJaV2NjTGpQZUdZMGUiLCJpYXQiOjE1NzU1NzUxNTcsImV4cCI6MTU3NTU3NTQ1N30.2q4KTyDUevkAAz7mJyp529Be1-ip3EC8P06Xarmz5ao

Request Body:

No request body is 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. 

{
    "page": {
        "page": 1,
        "pageSize": 3,
        "totalCount": 3
    },
    "contents": [
        {
            "guid": "5",
            "macAddress": "AB:BC:DD:EE:FF:DC",
            "status": "ACTIVE",
            "username": "",
            "deviceName": "",
            "location": "",
            "email": "",
            "expirationDate": "2020-07-28T22:07:52Z",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1/macRegistrations/5",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "parent",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "2",
            "macAddress": "AA:BB:CC:DD:EE:FF",
            "status": "REVOKED",
            "username": "",
            "deviceName": "",
            "location": "",
            "email": "",
            "expirationDate": "2020-07-28T22:05:39Z",
            "revokeInfo": {
                "date": "2020-07-27T22:06:54Z",
                "reason": "Updated MAC registration for same MAC address was imported",
                "user": null
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1/macRegistrations/2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "parent",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "1",
            "macAddress": "AA:BB:CC:DD:EE:FF",
            "status": "REVOKED",
            "username": "",
            "deviceName": "",
            "location": "",
            "email": "",
            "expirationDate": "2020-07-28T21:33:06Z",
            "revokeInfo": {
                "date": "2020-07-27T22:05:46Z",
                "reason": "Updated MAC registration for same MAC address was imported",
                "user": null
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1/macRegistrations/1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "parent",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/registrationLists/WorkflowRegistration-2de79119-f1da-4b7e-84b8-b0482911cae1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Core Cloudpath APIs