Licensing


Licensing

The licensing service maintains license templates, manages license assignments at the organizational level, and enforces licensing limits at the environment level. This service supports operations to create, read, update, and delete license resources associated with organizations.

License entitlements and enforcement

The licenses resource’s property values specify the licensing boundaries for the organization, such as:

  • Allow production environments
  • Allow SAML2 protocol applications
  • Allow custom schemas for users
  • Allow delegated administration
  • Allow custom authentication flows
  • Allow on-premises support (PingAccess, PingFed)
  • Set maximum number of environments
  • Set maximum number of users
  • Set license expiration date

License templates

The licenses service maintains templates that define a default set of properties for a given licensing package. For example, the default settings for a TRIAL licensing package do not allow the organization to create production environments. When a license package is associated with an organization, the license inherits the default values encoded in the package template, unless specific property values are overridden in the POST /organizations/{organizationId}/licenses request.

Licenses API operations

The licenses endpoints support the following operations:

For hands-on experience with the licenses 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.

Licenses data model

Property Description
applications.protocols A string that specifies the application connection protocols allowed. Options are OPENID_CONNECT and SAML2_IDP.
environments.allowDelegatedAdmin A boolean that specifies whether delegated administration is allowed.
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 have a hard-stop at expiration. All other licenses trigger an event to send a notification.
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.
onPremisesSupport.products A string that specifies the on-premises applications that can integrate with this organization. Options are PING_ACCESS and PING_FEDERATE.
package A string that specifies the the license template on which this license is based. This is a required property. Options are TRIAL, PLAN1, PLAN2, and CUSTOM.
prod_envs A boolean that specifies whether production environments are allowed.
schemas.custom A boolean that specifies whether custom user schemas are allowed.
signOnPolicy.allowCustomFlows A boolean that specifies whether custom sign-on policy flows are allowed.
users.max An integer that specifies the maximum number of users allowed per environment.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
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:

{
    "id": "{licenseId}",
    "package": "TRIAL",
    "organization": {
      "id": "{organizationId}"
    },
    "expiresAt": "2022-07-13T00:00:00Z",
    "environments": {
      "allowProduction": false,
      "allowDelegatedAdmin": true,
      "max": 10,
      "regions": ["NORTH_AMERICA", "EUROPEAN_UNION"]
    },
    "users": {
      "max": 100000
    },
    "schemas": {
      "allowCustom": true
    },
    "applications": {
      "protocols": ["OPENID_CONNECT", "SAML2_IDP"]
    },
    "signOnPolicy": {
      "allowCustomFlows": true
    },
    "onPremisesSupport": {
      "products": ["PING_ACCESS", "PING_FEDERATE"]
  }

Note: At this time, an organization can have only one active license. To change the license, you must delete the current active license and use a POST request to associate a new license with the organization.

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'

Create licenses

You can use POST /environments/{environmentId}/populations/ to create a new license resource associated with the specified organization.

curl -X POST "https://api.pingone.com/v1/organizations/{organizationId}/licenses" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "package": "TRIAL"
}"

In the request body, package is a required property. All other properties are optional, and if optional property values are not specified in the request, they inherit the values defined in the package template. This example creates a new license for the organization using default property values for all TRIAL package settings, including the expiresAt timestamp, which sets a date that is 30 days from the create date.

Update licenses

You can use PUT /organizations/{organizationId}/licenses/{licenseId} to update the property values for a license associated with the specified organization.

curl -X PUT "https://api.pingone.com/v1/organizations/{organizationId}/licenses/{licenseId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "package": "TRIAL",
  "expiresAt": "2022-07-13T00:00:00Z",
  "environments": {
    "allowProduction": false,
    "allowDelegatedAdmin": false,
    "max": 5,
    "regions": ["NORTH_AMERICA"]
  },
  "users": {
    "max": 100000
  },
  "schemas": {
    "allowCustom": true
  },
  "applications": {
    "protocols": ["OPENID_CONNECT", "SAML2_IDP"]
  },
}"

Delete licenses

The following sample shows the DELETE /organizations/{organizationId}/licenses/{licenseId} operation to delete the license associated with the specified organization.

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

When successful, the DELETE request returns a code 204 No Content message.