Policies

You can use REST API v2 calls to obtain information about existing policies, to create or editpolicies, and to delete policies

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

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 policy.
name String Yes sortBy, like No The display name for this policy; must be unique.
description String Yes sortBy, like Yes A string that can be used by third-party consumers. The string can be referenced using RADIUS attribute variables such as: DPSK.THIRDPARTY_ID
rule <Object> embedded Yes Neither Optional on create only, but not on any subsequent uses . The rules that are defined for this policy. Refer to the "Resource: rule" table below.
links[] Link array Yes No No This is an href link to the RADIUS attribute group property (attributeGroup) being used by the policy. This href can then be used in other API calls.
Note: You can change the attribute group of a policy by using a PUT request and including the href link to the new attribute group.

Resource: rule

Property Name Type Editable Filter or Sort Optional? Description
userNameRegex String Yes Neither Yes The regex for a user name that will be applied with this policy.
nasIdRegex String Yes Neither Yes The regex for the NAS Identifier that will be applied with this policy.
realmRegex String Yes Neither Yes The regex for the realm that will be applied with this policy. The realm is defined as "@***" following the user name. For example, with joe.smith@company.com the realm is company.com
dpskRefNameRegex String Yes Neither Yes The regex for the DPSK reference name that will be applied with this policy. This value is valid only for eDPSK Pools and is ignored for all other uses.
authGroupRegex String Yes Neither Yes The regex for the authentication groups that will be applied with this policy.
timeRange <Object> embedded Yes Neither Yes The regex for the time range that will be applied with this policy.
links Link <Object> Yes Neither Yes This is an href link to the RADIUS client property (radiusClient) if this property is being used by the policy. This href can then be used in the "rule" portion of a request body as in this example (where "234" is the ID of the RADIUS client):
"links": [
        {
            "rel": "radiusClient",
            "href": "https://somehost.cp.com/radius/client/234"
        }
    ]

Also, refer to RADIUS Clients.

Resource: timeRange

Property Name Type Editable Filter or Sort Optional? Description
when Enum <String> Yes Neither No When the policy will be applied:WEEKDAY, WEEKEND, ALL
start String <Time> Yes Neither No The time specified for this policy to allow access, in ISO 8601 formatted time.
end String <Time> Yes Neither No The time specified for this policy to prevent access, in ISO 8601 formatted time.

Policies 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.

Policies URIs and Actions

URI Action Description Return Codes
/policies GET Returns the list of policies.

401 - Unauthorized

200 - OK

POST Creates a policy.

401 - Unauthorized

201 - Created

/policies/{id} GET Returns the specific policy.

404 - Not Found

401 - Unauthorized

200 - OK

DELETE Deletes the specified policy. If the policy has been assigned to an eDPSK pool or PEAP, you will receive a "conflict" message when trying to delete the policy.

409 - Conflict

401 - Unauthorized

204 - No content

200 - OK

PUT Updates the specified policy. See the "Resource: Policies" table for the properties that can be edited.

409 - Conflict

401 - Unauthorized

204 - No content

200 - OK

Example of Using POST to Create a Policy

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

URI:

This example uses the following URI: 

 https://Jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/policies

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

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:

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

Note: The href link near the end of the request body shown below is the link to the RADIUS attribute group (with its ID, which is 1 in the example link) to be associated with the policy. 
{
    "name":"Policy2",
    "description":"Test Policy2 using Attribute1 and with userNameRegex and timeRange",
    "rule":{
                "userNameRegex":"user*",                                        
                "nasIdRegex":"Using Attribute",
                "realmRegex":"",
                "dpskRefNameRegex":"",
                "authGroupRegex":"","links":[],
                "timeRange": {
                                   "when": "WEEKEND",
                                   "startTime": "07:45:00",
                                   "endTime": "16:15:00"
                 },
                 "links": []
    },
    "links":[
                {
                     "rel":"attributeGroup",
                    "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/radiusAttributeGroups/1"
                }
     ]
}

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 policy) is included in the response body. 

{
    "guid": "2",
    "name": "Policy2",
    "description": "Test Policy2 using Attribute1 and with userNameRegex and timeRange",
    "rule": {
        "userNameRegex": "user*",
        "nasIdRegex": "Using Attribute",
        "realmRegex": "",
        "dpskRefNameRegex": "",
        "authGroupRegex": "",
        "timeRange": {
            "when": "WEEKEND",
            "startTime": "07:45:00",
            "endTime": "16:15:00"
        },
        "links": []
    },
    "links": [
        {
            "rel": "self",
            "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/policies/2",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "attributeGroup",
            "href": "https://jeff243.cloudpath.net/admin/apiv2/5XcTc6SjkHDL/radiusAttributeGroups/1",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        }
    ]
}

Parent topic: Core Cloudpath APIs