PingOne Authorize provides customers with a fine-grained, attribute-based, dynamic authorization decisioning capability. PingOne Authorize moves per-transaction authorization logic from customer applications to PingOne, enabling centralized control of authorization policy and reuse of policy across applications and contexts.

This service provides the following operations:

Runtime evaluation

• Runtime evaluation of decision requests against a given policy decision resource. For more information, refer to Policy Decision Authorization.

Decision endpoint management

• Creation of decision endpoints that allow efficient evaluation of policies developed in the PingOneAuthorize Policy Editor Service.

• Control over which version of the policies are deployed to each decision endpoint, giving your organization control over how and when policies are rolled out.

For more information, refer to Policy Decision Management.

The PingOne policy decision service provides operations to create, read, update and delete decision policy versions in PingOne.

Policy decision service data model

Policy decision management events generated

Refer to Audit Reporting Events for the events generated.

Response codes

The PingOne policy decision service provides an action for runtime evaluation of decision requests against a given policy decision resource.

Policy decision evaluation request data model

Policy decision evaluation response data model

Policy decision evaluation related resource links

Policy decision authorization events generated

Refer to Audit Reporting Events for the events generated.

The decision event format returned by a DECISION_ENDPOINT.DECISION_REQUEST_EVALUATED event uses terse keys to reduce storage requirements. The following table explains the meaning of each key returned in the decision event response.

Response codes

The PingOne Authorize API access management service provides tools to externalize the management and evaluation of access control policies for HTTP-based APIs. The access control policies defined in the API Service configuration are enforced through an API gateway, which delegates policy evaluation using a Ping Identity-provided integration kit that connects with the PingOne API.

The integration kit installed in your API gateway authenticates to PingOne. You configure a gateway and obtain a gateway credential. This credential is used to configure the API gateway integration kit. For more information, refer to PingOne Authorize API Gateway Integration Kits.

To create a gateway resource, refer to Create API Gateway Integration. In addition, API access management also uses the gateways credentials service. For more information, refer to Gateway Credentials.

The PingOne /environments/{{envID}}/apiServers endpoint provides operations to create, read, update, and delete API services in PingOne. An API service models a customer's APIs, which are then protected by the PingOne API access management service.

API service data model

Path parameter pattern syntax

If a path pattern has a type of PARAMETER, the following syntax rules apply to the parameter expression:

• The pattern must start with a slash.

• A single * (wildcard) matches any character except a /.

• A double ** matches the rest of the path. It cannot be followed by any characters in the pattern.

• A path segment can be captured with syntax like /{variable}.

• Nested captures are not allowed, meaning {name1{name2}} is an invalid expression.

• Partial path segment matches are not allowed, meaning /part1{part2} is an invalid expression.

• A literal left curly bracket, right curly bracket, backslash, or wildcard can be matched by preceding the character with a backslash: \{, \{, \\, \*.

• The following characters are not allowed in parameter names: '{', '}', '\', '/'.

• Parameter names must be unique within an expression, meaning /{name1}/resource/{name1} is an invalid expression.

• ASCII control characters are invalid anywhere in the pattern.

Limiting and filtering data

You can limit the number of results returned on the Read API Services request with the limit parameter. Refer to Pagination for more information about use of the limit parameter, as well as other methods of controlling pagination.

You can filter response data by applying a SCIM filtering expression to the Read API Services request. These SCIM operators can be applied to the following attributes:

• eq (equals)

  Supported attributes: authorizationServer.externalOAuthServer.id

Response codes

The PingOne /environments/{{envID}}/apiServers/{{apiServerID}}/operations endpoint provides operations to create, read, update, and delete API service operations in PingOne. Each operation is defined by one or more paths, and each path must have a unique pattern.

Path parameter pattern syntax

If a path pattern has a type of PARAMETER, the following syntax rules apply to the parameter expression:

• The pattern must start with a slash.

• A single * (wildcard) matches any character except a /.

• A double ** matches the rest of the path. It cannot be followed by any characters in the pattern.

• A path segment can be matched using a named parameter, with syntax like /{variable}.

• Nested named parameters are not allowed, meaning {name1{name2}} is an invalid expression.

• Partial path segment matches are not allowed, meaning /part1{part2} is an invalid expression.

• A literal left curly bracket, right curly bracket, backslash, or wildcard can be matched by preceding the character with a backslash: \{, \{, \\, \*.

• The following characters are not allowed in parameter names: '{', '}', '\', '/'.

• Parameter names must be unique within an expression, meaning /{name1}/resource/{name1} is an invalid expression.

• ASCII control characters are invalid anywhere in the pattern.

API service operations data model

Response codes

The PingOne /environments/{{envID}}/apiServers/{{apiServerID}}/deployment endpoint provides operations to read and deploy an API service resource.

To create, modify, or delete an API service resource, refer to API services.

API service deployment data model

API service deployment codes

The PingOne /environments/{{envID}}/externalOAuthServers endpoint provides operations to create, read, update, and delete external OAuth server resources in PingOne.

Refer to Using an external authorization server in PingOne Authorize AAM in the PingOne Admin Guide for more information.

External OAuth server data model

Limiting and filtering data

You can limit the number of results returned on the Read All External OAuth Servers request with the limit parameter. Refer to Pagination for more information about use of the limit parameter, as well as other methods of controlling pagination.

You can filter response data by applying a SCIM filtering expression to the Read All External OAuth Servers request. These SCIM operators can be applied to the following attributes:

• co (contains)

  Supported attributes: name

Response codes

The PingOne Authorize application resources and roles service provides endpoints to define custom roles and permissions within PingOne to protect external application resources.

To create and manage application roles and permissions, see:

• View application resources

  Provides endpoints to list the representations of external applications in PingOne. For create, update, and delete operations for application resources, refer to Application Resources.

• Application resource permissions

  Provides endpoints to define and manage permissions on the application resource.

• Application roles

  Provides endpoints to define and manage application roles in PingOne. Roles contain application permissions. Application roles can be assigned to PingOne users.

• Application roles permissions

  Provides endpoints to define and manage access control permissions, expected to be defined by a customer application developer. An application permission is comprised of an action and a protected resource, such as read:accounts. When a permission is added to a role, it creates a role entry. A subject assigned to a role is authorized for the permissions represented by the role's entries.

• Application role assignments by role

  Provides an endpoint to read application role assignments by role. The endpoint specifies a role ID in the request URL and the operation returns the role assignments associated with the identified role.

• User application role assignments

  Provides endpoints to define and manage application role assignments associated with user resources.

The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationResources endpoint provides operations to read application resources in PingOne. For information about create, update, and delete operations for application resources, refer to Create Application Resource, Update Application Resource, and Delete Application Resource.

API application resources data model

Response codes

The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationResources/{{appResourceID}}/permissions endpoint provides operations to create, read, update, and delete application resource permissions in PingOne.

Application resources permissions data model

Response codes

The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationRoles endpoint provides operations to create, read, update, and delete application roles in PingOne.

Application roles data model

Response codes

The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationRoles/{{appRoleID}}/permissions endpoint provides operations to add, read, and delete the permissions associated with application roles.

Application roles permissions data model

Response codes

The PingOne Authorize{{apiPath}}/environments/{{envID}}/applicationRoles/{{appRoleID}}/assignments endpoint provides operations to read application role assignments in PingOne.

Appliction role assignments data model

Response codes

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment. For information about how PingOne secures APIs, resources, and data, and what you can do to implement security measures for your PingOne deployment and applications, refer to Platform security.

PingOne API domains

This section discusses how PingOne API regional endpoints are entered in the domain name system (DNS). In DNS, and in our endpoints, the domain part of the uniform resource locator (URL) comprises three parts separated by periods, such as api.pingone.com: one of our service-specific subdomains, our PingOne domain name of pingone, and one of our top level domains.

We use Postman variables to manage this variety of domain parts in PingOne API endpoints. The later discussion is correct regarding the domain part that the variables evaluate to. However, to ease maintenance, the Postman environment template you get when you download a collection uses variables to isolate the TLD from the rest of the domain part and to isolate the domain part from the rest of the endpoint.

The environment template has a path variable for each subdomain. Each path variable uses another variable, {{tld}}, for the top level domain (TLD). Such as https://api.pingone.{{tld}}/v1 for {{apiPath}}. The tld variable is first in the environment template that you downloaded.

The table below shows the top level domain value for each region. To change your region, simply change the default {{tld}} value from com to your region's TLD.

The PingOne API includes the following domains:

The {{...Path}} variable in the sample requests stand for the PingOne service endpoint. Refer to Public endpoints in the PingOne for Developers Foundations guide for more information.

The Try a Request feature

Our documentation for the PingOne APIs includes an interactive Try a Request feature. Try a Request enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

Requests in Authentication and Authorization APIs do not have the Try a Request feature due to a Cross-Origin Resource Sharing (CORS) constraint.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. Refer to Postman Collection-Level Authorization for more information.

We use Postman to create our PingOne DaVinci Admin API docs, and have supplied our Postman collections for you to download. There's also an accompanying Postman Environment template already populated with the variables used in the collections.

If you aren't currently using Postman, you can install the free version. Refer to Download Postman to install Postman, either locally, or in your browser.

Refer to The PingOne DaVinci Admin API Postman collections for the collections you can download or fork.

For more information about our Postman environment variables, refer to The PingOne Postman environment template.

You'll also find all of the Postman collections for our documented PingOne use cases in our Workflow Library.

You can get the PingOne Authorize API Postman collection by following either of these methods for retrieving a Postman collection into your workspace:

1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If we update the source collection, you can pull those changes into the fork in your workspace.

2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve a collection

Refer to The PingOne Authorize API collections on this page.

1. Click the collection's Run In Postman button.

2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

   Note: You need to be logged in to your Postman account to retrieve the collection.

   

3. Follow the on-screen instructions to fork or import the collection. You're prompted to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a selected workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you'll see Pull changes on the context menu. When you click Pull changes, Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also elect to watch the collection, you'll receive notifications when the source changes.

If you import a collection, a copy is created in the selected workspace with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and use only some requests in a collection, a link back to the source is not needed.

You're not limited to choosing one method or the other. You can fork a copy to track the source and import a copy for experimentation, if you like.

The PingOne Authorize API collections

These Postman collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne Authorize APIs.

Collection	Description	Retrieve
PingOne Authorize	Postman requests for the PingOne Authorize API. Includes all environment variables. No example responses to make it easy to get started.
PingOne Authorize	Postman requests for the PingOne Authorize API. Includes all PingOne Platform API Reference documentation and example responses. No environment variables are included.

For more information about the Postman environment variables included when you download or fork one of our Postman collections, refer to The PingOne Postman environment template.

Our Postman collections use variables in the request URLs to specify the UUIDs for PingOne resources. When you click the Run in Postman button for a collection, these environment variables are included in your download or fork. Use these environment variables as a template to assign your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, refer to the following topic in the Postman documentation: Environments in Postman.

POST requests in the PingOne Authorize API Postman collections that create a resource and return a resource ID include a Postman script. This script automatically adds a resource variable to your active Postman environment, and uses the newly created ID as the value.

For example, the following request creates a new Authorize variable. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/variables

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top-level domain (TLD) associated with your organization. Refer to Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you'll want to add your environment's UUID to your active Postman environment as the value for the {{envID}} variable.

Requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne Postman collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request shown above:

POST {{apiPath}}/environments/{{envID}}/variables

If the request is successful, Postman adds a {{variableID}} variable to the current Postman environment automatically, and associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It's important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. You'll want to pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud, and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman doesn't copy it to the current value or use the initial value in the request, the request simply fails. In this case, you need to manually copy the initial value to the current value.

When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the Postman cloud impacts security. These initial values are available to anyone who has access to the workspace. If a workspace is public, you have a security issue.

Postman's recommended solution to exposing secrets is to Store secrets in your Postman Vault. Remember that Postman uses only current values in requests.

Variables you must value

When you download or fork a PingOne Postman collection, your workspace receives a set of Postman environment variables for you to use as a template. The variables that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. Our script associated with the request (shown on the request's Scripts tab) inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne do not have their values inserted automatically. You must manually add the correct value to these variables before making any requests in Postman: