Overview


What is the PingOne for Customers Platform API?

The PingOne for Customers API provides the interface to configure and manage your PingOne Organization.

What can you build with PingOne API?

The PingOne Platform is completely API driven. It gives developers the tools to interact with the Platform to automate common tasks, create custom administration tools, and integrate enterprise and third-party applications with the Platform.

PingOne API model

The PingOne Platform includes the following entities.

API Model

Organizations

PingOne uses an organization-based model to define tenant accounts and their related entities within the PingOne Platform. The Organization is the top-level identifier. It defines your entire enterprise within the Platform.

Environments

An organization contains one or more environments. Environments define separate working domains within an organization. Environments are used to model regions within a large global enterprise such as NA (North America) or EU (European Union). They are also used as the defining entity to segregate enterprise operations by functionality, staging environments, or configurations.

Environments contain the core resources on which all identity services are built. Environments encompass:

  • Populations

    In PingOne, a population defines a set of users, similar to an Organizational Unit (OU). In a given environment, you can use populations to simplify the management of users. For example, you can create a population for similar types of users and apply a password policy to that population. You must create at least one population before you can create users. An individual user cannot belong to more than one population simultaneously, but users can be moved to a different populations.

  • Users

    These are unique user entities that interact with the applications and services within the environment to which the they are assigned. An user resource in PingOne is the full representation of a user profile, including the the user’s relationships, roles, and attributes. Users are associated with populations instead of defined within a population. The user’s association with a population is established as a property on the user resource.

  • Applications and Resources

    Applications in PingOne define the connection between the PingOne Platform and the actual application (also thought of as the client configuration). Resources represent the connections to external services, enabling secure access to PingOne resources and other defined external resources.

  • Activities

    Activities are collections of user-activity information such as login attempts, password reset attempts, and total active user counts. This audit data may be exported, reported on, or streamed out to customer Security Information and Event Management (SIEM) solutions.

  • Branding and Images

    User interface branding elements are defined in the branding service. This service contains configuration properties for elements of the PingOne interface that can be branded. All end user interfaces are branded according to the theme defined in the associated branding resource. The images service provides the interface to upload custom branding image files to our Content Delivery Network (CDN) and manage the lifecycle of those images.

  • Password Policies

    These resources represent the password policies that can be applied to users within an environment.

  • signOnPolicies

    These resources represent the sign-on workflow policies to establish an authentication flow during login, re-authentication, step-up, or registration actions that identify and verify users.

    Note: The authentication workflows are part of the authentication API. The signOnPolicy resource is a proxy back to other APIs to perform authentication actions.

Roles, Entitlements, and Permissions

Roles, permissions, and entitlements are defined at the root of the platform. Roles are assigned to users, and these user roles include a scope property to grant the user permissions corresponding to the role. For example, a role of Identity Admin contains permissions allowing the subject to read and edit user data. When this role is assigned to a user, it can be assigned with the scope property that identifies a population or an environment to which the permissions apply.

Note: Application permissions are described using scopes rather than roles. Scopes are more narrowly defined roles in that a scope cannot cross an environment boundary, and it is restricted to a specific task. For example, the p1:read:env:user scope grants permission to read user resource data only; it does not grant permission to perform create, update, or delete operations on user resources.

API endpoints

The PingOne Platform API includes the following public endpoints:

  • api.pingone.com

    This is the primary endpoint for calling PingOne API Services. You can use this endpoint to map requests to directory, application management, and user management resources. For example, the following URL identifies the endpoint path to perform user management operations: http://api.pingone.com/v1/environments/{environmentId}/users/.

  • auth.pingone.com

    This is the authorization and authentication endpoint called to request the access token required to authenticate PingOne API requests. For example, the following URL identifies the endpoint to submit a client_credentials request to the authentication service to acquire an access token: https://auth.pingone.com/as/token.oauth2.