PingOne Platform APIs

Platform Auth APIs

The PingOne Auth APIs provide services to query the authorization server, run authentication workflows, and receive access tokens from the authorization server. An authentication workflow can include sign-on policies that specify local authentication actions (login), multi-factor authentication actions, and other external sign-on actions. The Authentication API includes the flow orchestration and action services needed to configure an authentication workflow. It also supports initiation of PingOne DaVinci flows and flow policies.

The authorization service allows a resource owner (you) to share protected resources with a client (an application) without giving the client your password. Instead, the resource owner interacts with an *authorization server (PingOne) that verifies your credentials and issues an access token to the client. The client uses the token to access only the protected resources stored on a resource server (your stuff) that you’ve granted, as specified by the scopes (permissions) defined in the token.

The PingOne flow service (or the DaVinci flow) specifies the authentication actions to complete the checks needed to confirm that it’s you. For example, if the authentication flow requires a username/password check (a login action) and a one-time passcode check (an MFA action), then both actions must be completed successfully before the authorization server can issue an access token.

A typical flow starts with a request to the PingOne authorization server. The authorization server returns a flow ID that initiates the authentication flow. After the flow completes all the verification steps, the session is passed back to the authorization service to generate the access token. The diagram below shows the steps.

Authorize and flow services

In the authorization and authentication API sample requests shown in this document, the {{authPath}} variable in the sample requests represents the regional domain for the PingOne authorization and authentication services. Refer to PingOne API domains for more information.

The PingOne Auth APIs include the following entities.

Authorization server

The PingOne authorization server (as) service configures the authorization grants that are used to authenticate users and provide access to resources. This service includes the following entities:

  • authorize

    Queries PingOne (or an external resource owner) to get an authorization grant.

  • resume

    Continues the processing of an authorization request after the completion of an authentication flow.

  • userinfo

    Returns claims about the authenticated user resource.

  • token

    Obtains an access token by presenting its authorization grant.

  • jwks

    The JSON Web Key (jwks) is a JSON representation of the cryptographic key.

  • .well-known/openid-configuration

    The discovery endpoint, used in multi-tenant configurations to support multiple issuers per host.

  • signoff

    The end session endpoint called by the flow orchestration service to initiate the logout flow.

For more information, refer to OpenID Connect/OAuth 2 and Authorization and authentication by application type.

Flows

The PingOne flow orchestration service configures the steps required to authenticate the application or user that initiated the authentication request. The service is responsible for initiating the authentication session and making calls to specific actions required by the authentication workflow.

For more information, refer to Flows and Authentication flow states.

OAuth 2 and OpenID Connect

OpenID Connect is an authentication protocol that PingOne connected applications can use to authenticate users and get user data through claims. PingOne can also act as an OAuth 2 authorization server to authorize clients to access protected resources using access tokens. For example, PingOne uses OAuth 2 to protect access to PingOne management APIs.

The OAuth 2 framework defines several methods by which a client can obtain authorization to access protected resources using an access token. The access token represents authorization granted to the client for a set of scopes. Scopes are string identifiers understood by both the authorization server and the resource server to represent the specific boundaries of access. The client can use the access token as a credential for accessing data on a resource server.

For more information about access tokens, refer to Access tokens.

SAML 2.0

The SAML service provides support for the SAML protocol to authorize clients and allow clients to obtain a requestor’s authentication state. The SAML service implements functions to initiate SAML 2.0 single sign-on and single logout authentication flows.

For more information, refer to SAML 2.0.

Additional PingOne resources

If you’re new to PingOne, the following topic links will help you learn more about PingOne APIs.

  • PingOne for Developers Getting Started

    This collection of topics helps you create your first application connection using the PingOne admin console application and get a JSON Web Token for the application you created. With your admin access token, you can make calls to the Pingone resource server.

  • Download the PingOne Postman collections

    This topic includes downloads for the PingOne Platform API Postman master collection.

  • Workflow library

    The PingOne use cases provide workflows for common PingOne configurations and sign-on flows. Each use case includes a Postman collection linked to a Run in Postman button, enabling you to load (and run) the use case collections into your Postman workspace. You can also download the workflow Postman collections used in the Workflow Library.

  • PingOne for Developers Foundations

    These topics provide a deeper dive into PingOne platform authorization and authentication concepts and workflows. It includes detailed information about access tokens, ID tokens, user scopes, built-in roles, and sign-on flows.

  • PingOne Admin APIs

    This document describes the PingOne platform admin APIs for managing environments, applications, users, and identity providers.

  • PingOne native SDKs

    You’ll find here the documentation for the PingOne mobile SDKs. Currently, this includes the PingOne MFA SDKs, the PingOne Neo SDKs, and the PingOne Protect SDKs.