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
beginsAt The date and time this license begins.
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 NORTH_AMERICA and EUROPEAN_UNION.
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.
organization.id A string that specifies the organization resource’s unique identifier associated with the license.
id A string that specifies the license resource’s unique identifier.
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.
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.

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/dde708a2-2303-4d7a-bbf7-d72abe80fd07/licenses"
    }
  },
  "_embedded": {
    "licenses": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/organizations/dde708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/52dab8f4-aa4b-4615-990c-6ba9a10ecc2a"
          },
          "organization": {
            "href": "https://api.pingone.com/v1/organizations/dde708a2-2303-4d7a-bbf7-d72abe80fd07"
          }
        },
        "beginsAt": "2019-05-21T17:47:23.574Z",
        "environments": {
          "allowProduction": false,
          "max": 5,
          "regions": [
            "NORTH_AMERICA"
          ]
        },
        "expiresAt": "2019-08-19T17:47:23.574Z",
        "id": "52dab8f4-aa4b-4615-990c-6ba9a10ecc2a",
        "organization": {
          "id": "dde708a2-2303-4d7a-bbf7-d72abe80fd07"
        },
        "status": "EXPIRED",
        "package": "TRIAL",
        "users": {
          "max": 10000000
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/organizations/dde708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/57f0efac-37d9-4a17-8a35-196bb3362983"
          },
          "organization": {
            "href": "https://api.pingone.com/v1/organizations/dde708a2-2303-4d7a-bbf7-d72abe80fd07"
          }
        },
        "beginsAt": "2019-06-06T19:29:13.671Z",
        "environments": {
          "allowProduction": true,
          "max": 50,
          "regions": [
            "EU",
            "NORTH_AMERICA"
          ]
        },
        "expiresAt": "2020-06-06T19:34:13.615Z",
        "id": "57f0efac-37d9-4a17-8a35-196bb3362983",
        "organization": {
          "id": "dde708a2-2303-4d7a-bbf7-d72abe80fd07"
        },
        "package": "STANDARD",
        "status": "ACTIVE",
        "users": {
          "max": 10000000
        }
      }
    ]
  },
  "count": 2,
  "size": 2
}

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/cd8f7878-5a76-4792-93dc-f79ce47c84a4/licenses?filter=status%20eq%20%22active%22"
    }
  },
  "_embedded": {
    "licenses": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/organizations/cd8f7878-5a76-4792-93dc-f79ce47c84a4/licenses/5453f81e-8e72-4f9f-b5ab-8cabd7377188"
          },
          "organization": {
            "href": "https://api.pingone.com/v1/organizations/cd8f7878-5a76-4792-93dc-f79ce47c84a4"
          }
        },
        "assignedEnvironments": [
          {
            "id": "ee77f921-1bb3-4437-baca-b95bfd1e6cdd"
          }
        ],
        "beginsAt": "2019-11-05T15:39:32.835Z",
        "environments": {
          "allowProduction": true,
          "max": 15,
          "regions": [
            "NORTH_AMERICA",
            "EU",
            "AP"
          ]
        },
        "expiresAt": "2029-09-20T15:39:32.835Z",
        "id": "5453f81e-8e72-4f9f-b5ab-8cabd7377188",
        "name": "GLOBAL",
        "organization": {
          "id": "cd8f7878-5a76-4792-93dc-f79ce47c84a4"
        },
        "package": "GLOBAL",
        "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/dde708a2-2303-4d7a-bbf7-d72abe80fd07/licenses/52dab8f4-aa4b-4615-990c-6ba9a10ecc2a"
    },
    "organization": {
      "href": "https://api.pingone.com/v1/organizations/dde708a2-2303-4d7a-bbf7-d72abe80fd07"
    }
  },
  "beginsAt": "2019-05-21T17:47:23.574Z",
  "environments": {
    "allowProduction": false,
    "max": 5,
    "regions": [
      "NORTH_AMERICA"
    ]
  },
  "expiresAt": "2019-08-19T17:47:23.574Z",
  "id": "52dab8f4-aa4b-4615-990c-6ba9a10ecc2a",
  "organization": {
    "id": "dde708a2-2303-4d7a-bbf7-d72abe80fd07"
  },
  "package": "TRIAL",
  "users": {
    "max": 10000000
  }
}