Licensing


License entitlements and enforcement

The property values of the license resource specify the licensing boundaries. The license identifies the organization that owns the license, the licensing package type, and the expiration date for the license. The following entitlements are also defined in the licensing package:

For environments:

  • Allow or deny production environments
  • Designate the maximum number of environments allowed by the organization
  • Designate the allowed regions

For users and applications:

  • Set the maximum number of users for the organization

License API operations

The licenses endpoints support the following operations:

For hands-on experience with the license API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

License data model

Property Description
assignedEnvironments.id An array of strings that specifies the environment IDs associated with this license.
beginsAt The date and time this license begins.
environments.allowCustomDomain A boolean that specifies whether the license supports creation of a custom domain.
environments.allowProduction A boolean that specifies whether production environments are allowed.
environments.max An integer that specifies the maximum number of environments allowed.
environments.regions A string that specifies the allowed regions associated with environments. Options are NA, EU, and AP.
expiresAt The date and time this license expires. TRIAL licenses stop access to PingOne services at expiration. All other licenses trigger an event to send a notification when the license expires but do not block services.
id A string that specifies the license resource’s unique identifier.
intelligence.allowGeoVelocity A boolean that specifies whether to use the intelligence geo-velocity feature. For TRIAL (unpaid) licenses, the default value is true. For other license package types, adoption of the feature determines the default value.
intelligence.allowReputation A boolean that specifies whether to use the intelligence IP reputation feature. For TRIAL (unpaid) licenses, the default value is true. For other license package types, adoption of the feature determines the default value.
mfa.allowPushNotification A boolean that specifies whether push notifications are allowed. For TRIAL (unpaid) licenses, the default value is true. For other license package types, adoption of the feature determines the default value.
name A string that specifies a descriptive name for the license. This is a required property in a license name update request. Valid characters consists of any Unicode letter, mark, numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen. The maximum length of a name is 255 characters.
organization.id A string that specifies the organization resource’s unique identifier associated with the license.
package A string that specifies the license template on which this license is based. This is a required property. Options are TRIAL, STANDARD, PREMIUM, and GLOBAL.
replacesLicense.id A string that specifies the license ID of the license that is replaced by this license.
replacedByLicense.id A string that specifies the license ID of the license that replaces this license.
status A string that specifies the status of the license. Options are ACTIVE, EXPIRED, and FUTURE.
terminatesAt An optional attribute that designates the exact date and time when this license terminates access to PingOne services. This attribute can be added to any licensing package.
users.max An integer that specifies the maximum number of users allowed per environment.
users.annualActiveIncluded An integer that specifies a soft limit on the number of active identities across all environments on the license per year. This property is not visible if a value is not provided at the time the license is created.
users.monthlyActiveIncluded An integer that specifies a soft limit on the number of active identities across all environments on the license per month. This property is not visible if a value is not provided at the time the license is created.

Response codes

Code Message
200 Successful operation.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.

Endpoint examples

Get licenses

The following sample shows the GET /organizations/{organizationId}/licenses operation to return the complete list of license resources associated with the specified organization.

curl -X "GET" "https://api.pingone.com/v1/organizations/{organizationId}/licenses" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses"
    }
  },
  "_embedded": {
    "licenses": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983"
          },
          "organization": {
            "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07"
          }
        },
        "assignedEnvironments": [
          {
            "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          {
            "id": "e6263e4c-8436-46ea-b486-b6369d84584d"
          }
        ],
        "beginsAt": "2019-06-06T19:29:13.671Z",
        "environments": {
          "allowCustomDomain": true,
          "allowProduction": true,
          "max": 50,
          "regions": [
            "NORTH_AMERICA",
            "EU"
          ]
        },
        "expiresAt": "2020-06-06T19:34:13.615Z",
        "id": "57f0efac-37d9-4a17-8a35-196bb3362983",
        "intelligence": {
          "allowReputation": true,
          "allowGeoVelocity": true
        },
        "mfa": {
          "allowPushNotification": true
        },
        "name": "Updated North America Test License.",
        "organization": {
          "id": "ede708a2-2303-4d7a-bbf7-d72abe80fd07"
        },
        "package": "INTERNAL",
        "status": "ACTIVE",
        "users": {
          "max": 10000000
        }
      }
    ]
  },
  "count": 1,
  "size": 1
}

An organization can have several licenses, such as a TRIAL license and a STANDARD license. For organizations with more than one license, you can use a filter with the GET /organizations/{organizationId}/licenses operation to return the list of licenses in descending order, showing the most recent licenses first.

curl -X "GET" "https://api.pingone.com/v1/organizations/{organizationId}/licenses?filter=beginsAt lt "{now}"&order=-beginsAt" \
-H 'Authorization: Bearer jwtToken'

In the request, the {now} filter parameter variable represents a datetime value in the format 2019-06-25T16:55:44.225Z. The order=-beginsAt parameter orders the list showing the most recent license first.

In addition, you can use the filtering expression ?filter=status eq "active" to return licenses that have a status value of ACTIVE.

curl -X "GET" "https://api.pingone.com/v1/organizations/{organizationId}/licenses?filter=status eq "active" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses"
    }
  },
  "_embedded": {
    "licenses": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983"
          },
          "organization": {
            "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07"
          }
        },
        "assignedEnvironments": [
          {
            "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          {
            "id": "e6263e4c-8436-46ea-b486-b6369d84584d"
          }
        ],
        "beginsAt": "2019-06-06T19:29:13.671Z",
        "canCreateCustomDomain": "false",
        "environments": {
          "allowProduction": true,
          "max": 50,
          "regions": [
            "NORTH_AMERICA",
            "EU"
          ]
        },
        "expiresAt": "2020-06-06T19:34:13.615Z",
        "id": "57f0efac-37d9-4a17-8a35-196bb3362983",
        "intelligence": {
          "allowReputation": true,
          "allowGeoVelocity": true
        },
        "mfa": {
          "allowPushNotification": true
        },
        "name": "Updated North America Test License.",
        "organization": {
          "id": "ede708a2-2303-4d7a-bbf7-d72abe80fd07"
        },
        "package": "INTERNAL",
        "status": "ACTIVE",
        "users": {
          "max": 10000000
        }
      }
    ]
  },
  "count": 1,
  "size": 1
}

Get one license

You can use GET /organizations/{organizationId}/licenses/{licenseId} to view a license associated with the specified organization. The following sample shows the operation to get information about a single license. The license ID is specified in the request URL.

curl -X "GET" "https://api.pingone.com/v1/organizations/{organizationId}/licenses/{licenseId}" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983"
    },
    "organization": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07"
    }
  },
  "assignedEnvironments": [
    {
      "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    {
      "id": "e6263e4c-8436-46ea-b486-b6369d84584d"
    }
  ],
  "beginsAt": "2019-06-06T19:29:13.671Z",
  "environments": {
    "allowCustomDomain": true,
    "allowProduction": true,
    "max": 50,
    "regions": [
      "EU",
      "NORTH_AMERICA"
    ]
  },
  "expiresAt": "2020-06-06T19:34:13.615Z",
  "id": "57f0efac-37d9-4a17-8a35-196bb3362983",
  "intelligence": {
    "allowReputation": true,
    "allowGeoVelocity": true
  },
  "mfa": {
    "allowPushNotification": true
  },
  "name": "Updated North America Test License.",
  "organization": {
    "id": "ede708a2-2303-4d7a-bbf7-d72abe80fd07"
  },
  "package": "INTERNAL",
  "status": "ACTIVE",
  "users": {
    "max": 10000000
  }
}

Update a license name

You can use PUT /organizations/{organizationId}/licenses/{licenseId}/name to update the name property value for a license associated with the specified organization. The name property provides a custom name for the license to describe its use within the organization.

curl -X PUT "https://api.pingone.com/v1/organizations/{organizationId}/licenses/{licenseId}/name" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name": "Internal Test License"
}"

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983/name"
    },
    "license": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983"
    }
  },
  "name": "Internal Test License"
}

Get a license name

You can use GET /organizations/{organizationId}/licenses/{licenseId}/name to retrieve the name property value for a license associated with the specified organization.

curl -X GET "https://api.pingone.com/v1/organizations/{organizationId}/licenses/{licenseId}/name" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983/name"
    },
    "license": {
      "href": "https://api.pingone.com/v1/organizations/ede708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983"
    }
  },
  "name": "Internal Test License"
}