Conventions


PingOne Authentication API requests

Authorization

To make a call to the PingOne Authentication API, you’ll need an OAuth 2.0 access token for API authentication. The access token is accepted per RFC 6750, most commonly via the Authorization HTTP request header. For more information about acquiring an access token, see Application authorization and authentication.

HTTP methods

The PingOne API supports the following HTTP methods. Note that a resource may not support all listed methods below. When a method is not supported, the platform returns a 405 METHOD NOT ALLOWED error in the response.

  • POST

    Creates a new resource in the collection. If a specific resource is identified, it performs an operation on that resource.

  • PUT

    Creates a new (complete) resource in the collection. If a specific resource is identified, it updates all attribute values of the resource.

  • PATCH

    Updates the attributes on an object or a partial update for the specified attributes.

  • GET

    Lists or queries a collection of resources. If a specific resource is identified, it returns the attribute values for the specific resource.

  • DELETE

    Deletes or unlinks a resource from the collection.

A resource supports updating either by replacing the resource (PUT) or partially updating the resource (PATCH). HTTP method overrides are also supported using the X-HTTP-Method-Override header.

Replacing a resource

A PUT request is a replace operation. Requests submitted using PUT will replace attribute values specified in the request and clear any attribute values that aren’t specified.

A null value is represented in a resource by omitting the property, although you can specify null to explicitly clear the value.

Partial updates to a resource

A PATCH operation performs partial updates of a resource. The body of a PATCH operation is similar to that of a PUT operation. However, omitting an attribute in a PATCH operation results in the attribute being ignored.

You can use a value of null to explicitly clear the value.

HTTP method overrides

The PingOne API is designed to be accessible to a large range of clients, including both public clients (such as Javascript) and restricted clients. For HTTP method-restricted clients, an alternate method is supported using the X-HTTP-Method-Override header. When this header is present, the value of this header is used as the method type for the operation.

Here is a sample that overrides the POST HTTP method with a PUT method. The PingOne API will then treat this as a PUT request.

POST /{environmentId}/flows/12345 HTTP/1.1
X-HTTP-Method-Override: PUT
Authorization: Bearer jwtToken
{
  "_links" : {
    "self" : { "href" : "https://auth.pingone.com/{environmentId}/flows/12345" }
  },
  "attribute1" : "value1",
  "attribute2" : "value2",
  "attribute3" : "value3",
 ...
}

Supported data exchange formats

The PingOne API supports JSON as the data exchange format. The Content-type request header for the API call identifies the format of the request body for PUT, POST, and PATCH operations. Here is a sample that identifies JSON as the data exchange type:

curl -X PATCH "https://auth.pingone.com/{environmentId}/flows/{id}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "attribute1" : "value1",
  "attribute2" : "value",
}"

Link expansion

You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand query string parameter in the request.

Here is a sample that requests data for a specific user and expands the requiredStep attribute to show the attribute data.

GET {environmentId}/flows/{Id}?expand=requiredStep

Without the expand parameter in the query, the returned JSON for the requiredStep resource looks like this:

{
  ...

  "requiredStep": {
    "href": "http://auth.pingone.com/feff791f-a12f-44ec-a696-53be4ac1f9c2/flows/21731b50-6b54-41b0-8454-9cd9de62a7a1/steps/4567791f-a12f-44ec-a696-53be4ac1f9c2",
    "id": "4567791f-a12f-44ec-a696-53be4ac1f9c2"
  },

  ...
}

When using the expand parameter in the request, the returned JSON for the requiredStep resource looks like this:

{
  ...

  "requiredStep": {
    "href": "http://auth.pingone.com//feff791f-a12f-44ec-a696-53be4ac1f9c2/flows/21731b50-6b54-41b0-8454-9cd9de62a7a1/steps/4567791f-a12f-44ec-a696-53be4ac1f9c2",
    "id": "4567791f-a12f-44ec-a696-53be4ac1f9c2",
    "flow" : "8790791f-a12f-44ec-a696-53be4ac1f9c2",
    "status" : "pending",
    "action" : {
      "id:" "12112791f-a12f-44ec-a696-53be4ac1f9c2",
      "type:" "LOGIN"
    },
    "created" : "2017-12-15T19:56:38.460Z",
    "environment" : {
      "href" : "https://api.pingone.com/v1/feff791f-a12f-44ec-a696-53be4ac1f9c2",
      "id" : "feff791f-a12f-44ec-a696-53be4ac1f9c2"
    }
  ...
}

Note: If needed, you can specify multiple resources to expand in the query string by listing multiple attribute names separated by commas.

PingOne Authentication API responses

HTTP response headers

The PingOne API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.

The following HTTP Headers are returned by every operation:

  • Access-Control-Allow-Headers

    This header is used in response to a preflight request to indicate the HTTP headers can be used when making a request.

  • Access-Control-Allow-Max-Age

    This header specifies how long the results of a preflight request can be cached.

  • Access-Control-Allow-Methods

    This header specifies specifies the method or methods allowed when accessing the resource in response to a preflight request.

  • Cache-Control

    This header specifies specify directives for caching mechanisms in both requests and responses.

  • Content-Type

    This header specifies the data exchange format for the result data. For the PingOne APIs, this value should be application/HAL+json.

  • Correlation-Id

    This is a custom header.

  • Date

    This is the date the response was sent.

  • Expires

    This shows the date and time when the response expires.

  • Pragma

    This is used for backwards compatibility with HTTP/1.0 caches where the Cache-Control HTTP/1.1 header is not yet present.

  • Strict-Transport-Security

    This lets a web site tell browsers that it should only be accessed using HTTPS, instead of using HTTP.

  • Transfer-Encoding

    This specifies the form of encoding used to safely transfer the entity to the user.

  • Vary

    This determines how to match future request headers to decide whether a cached response can be used rather than requesting a fresh one from the origin server. It is used by the server to indicate which headers it used when selecting a representation of a resource in a content negotiation algorithm.

  • Via

    This is used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain.

  • X-Content-Type-Options

    This is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed.

  • X-Frame-Options

    This denies rendering in a frame where there is a frame mismatch.

  • X-XSS-Protection

    This is a feature of Internet Explorer, Chrome and Safari that stops pages from loading when they detect reflected cross-site scripting (XSS) attacks.

HTTP response codes

The PingOne API returns the status of an operation as a registered HTTP response code. The HTTP response codes can be summarized as:

  • 200-299

    Confirms a successful call.

  • 300-399

    Indicates that the call or subsequent calls should be made to another resource.

  • 400-499

    Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.

  • 500-599

    Shows that an error occurred, generally due to an issue with the service (for example, a service outage).

Operations may also return additional information about a failed operation in the HTTP response body.

Synchronous responses

Responses for synchronous operations have the following behavior:

  • GET operations

    A request that returns a body also returns the code 200 OK with the resource in the body of the response.

  • POST operations

    A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource.

  • PUT or PATCH operations

    A request that updates a resource returns 200 OK and the full resource in the body.

  • DELETE operations

    A request that deletes a resource returns 204 NO CONTENT.

Asynchronous responses

The PingOne API may create a long-running or asynchronous operation that can be monitored by a client. An asynchronous operation will have the following behavior:

  • POST operations

    Responses include 202 ACCEPTED with a Location header containing the location of the newly created operation. The client can poll the provided location to check the status of the operation. The operation may also return a suggested number of seconds for the client to recheck the status using the Retry-After HTTP header.

  • Cancelling long-running operations

    Some resources may allow the client to cancel an operation by performing a DELETE request on the created resource.

  • Clean up

    The PingOne API will clean up operation history according to the application requirements (such as, keep the last n results, or purge results after the client has verified its success).

Response data structure

All PingOne API resources return data using the HAL+JSON content type. The HAL media type provides a common format for linking API resources. HAL conventions adopted by the PingOne APIs result in an easily readable structure for resource links and for expressing embedded resources contained within parent resources. The following sample shows how embedded resources are structured in the response data.

{
    "count": 2,
    "size": 2,
    "_links": {
        "self": {
            "href": "https://auth.pingone.com/..."
        }
    },
    "_embedded": {
        "signOnPolicies": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "actions": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/actions"
                    }
                },
                "id": "1c006010-a765-448b-84bf-32199c4af3c3",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Multi_Factor",
                "description": "A sign-on policy that requires primary username and password along with an out-of-band OTP"
            },

For collections, the result data returns a count and size attribute, and all API requests return a self URL under the _links attribute that identifies the URI of the main resource.

The _embedded attribute lists all the results in the collection. In the sample above, the count attributes tells you that there are two signOnPolicies in the collection.

Relationships between resources or operations can be described as follows:

  • Relationships (one-to-one).

    Where a resource or resources is directly related to another resource (such as, employee to manager, user to population, logo to brand), the relationship is generally represented by an attribute as a first-class citizen of the resource. For example:

    • _links object : Contains an href to the actual resource.

    • Payload : Contains the reference as an attribute with the ID. The name of the _links attribute and the attribute in the payload must be the same).

    • Expandable : Yes.

  • Relationships (one-to-many or many-to-one).

    Where a resource may be related to a collection or to many resources. For example, a user to group membership:

    • _links object : Contains an href to the actual resource or collection.

    • Payload : May contain the reference as an attribute with the ID. The name of the _links attribute and the attribute in the payload must be the same).

    • Expandable : No.

  • Informal relationships and links.

    Provides navigation and self-discovery of the API and its related resources (such as, next page of search results, next authentication service to invoke, or with which environment the resource is associated). For example:

    • _links object : Contains an href to the actual resource, collection, or URL.

    • Payload : Cannot contain the reference as an attribute.

    • Expandable : No.

These relationships and references are represented as follows:

  • Links are represented using JSON HAL conventions (such as, in a _links object).

  • Links are represented as absolute URLs.

  • Links can be expanded using the expand parameter. See [Link expansion](#Link expansion). The links can also be referenced via the “property-as-resource” pattern.

  • References as attributes have an id value and may also have additional attributes (such as, name).

Errors

Errors generated by the PingOne API are intended to allow you to resolve specific errors programmatically. An error response consists of a high-level error code that must be handled by the client and optional details containing specific information on how to resolve the fault. The PingOne API errors return a response payload formatted as follows:

Attribute Required Description
id Yes A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client with server-side activity included for troubleshooting purposes.
code Yes A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all PingOne services and is human readable (such as a defined constant rather than a number).
message Yes A short description of the error. This message is intended to assist with debugging and is returned in English only.
target No The item that caused the error (such as a form field ID or an attribute inside a JSON object).
details No Additional details about the error. Optional information to help resolve the error and to display to users.
innererror No Additional details to assist the client developer resolve the fault (primarily for UI validation reasons). The following attributes can be used in the innererror object:
  • rangeMinimumValue. Errors that failed due to range violation. This attribute represents the minimum value of the range.
  • rangeMaximumValue. The maximum range or value of an attribute.
  • allowedPattern. A regex pattern describing an acceptable input pattern.
  • allowedValues. A list describing acceptable values.
  • maximumValue. The maximum value allowed for the request.

Caching

The PingOne API generally implements HTTP caching of operation responses. When HTTP caching is implemented, the following HTTP response headers are included:

  • ETag

    An arbitrary string for the version of a representation. This includes the media type in the hash value. For example: ETag: “686897696a7c876b7e”.

  • Date

    The date and time the response was returned. For example: Date: Sun, 06 Nov 1994 08:49:37 GMT.

  • Cache-Control

    The maximum number of seconds a response can be cached. If caching is not supported for the response, the value is no-cache. For example: Cache-Control: 360 or Cache-Control: no-cache.

  • Expires

    If Cache-Control is supplied, this header contains the timestamp for when the response expires. If caching is not supported for the response, this header is not present. For example: Expires: Sun, 06 Nov 1994 08:49:37 GMT.

  • Pragma

    When the Cache-Control value is no-cache, this header is also set to no-cache. Otherwise, it isn’t present. For example: Pragma: no-cache.

  • Last-Modified

    The timestamp for when the resource itself was last modified. For example: Last-Modified: Sun, 06 Nov 1994 08:49:37 GMT.

  • Varies

    This header is included for user-specific headers (such as, Authorization) in multi-tenant scenarios.

Paging, ordering, and filtering collections

Pagination

The PingOne API supports cursor-based pagination to return large collections in consumable pages for a client. When an operation supports pagination, the following conventions are used:

  • Page limits

    Page limits are requested using the limit query string. If the limit parameter value is omitted, the operation returns the lesser of the service-defined maximum page size or the number of items in the collection.

  • Self, next, and previous links

    The response body includes a self link in the _links object. If there are more pages available, the response includes a next link in the _links object. If there are previous pages of results available, the response includes a prev link in the _links object.

  • Multiple pages

    If there is more than one page, the response returns a URL-safe cursor in the cursor query string parameter for the next or prev links.

  • Response metadata

    The response may include the following metadata about the results in the body of the payload:

    • count (optional).

      Describes the number of items in the collection or result set (such as, the total item count). If a response does not return a count attribute, the client is to assume there are many.

    • size (optional).

      Describes the size of the page of results (such as, the limit or service-defined maximum page size).

Here is a sample request that limits the collection returned to a maximum of 2.

GET /environments/{environmentId}/signOnPolicies?limit=2 HTTP/1.1

Here is the response body.

HTTP/1.1 200 OK
{
 "_links" : {
  "self" : { "href" : "https://api.pingone.com/v1/environments/{id}/signOnPolicies?limit=2" },
  "next" : { "href" : "https://api.pingone.com/v1/environments/{id}/signOnPolicies?cursor=xygdhs&limit=2" }
 },
 "count" : 50,
 "size" : 2,
 "_embedded" : {
  "signOnPolicies" [
   {
    "name" : "LOGIN",
    "id" : "12345-aaa-12345"
   },
   {
    "name" : "MULTIFACTOR",
    "id" : "12345-aaa-12346"
   }
  ]
 }
}

Ordering collections

The PingOne API supports ordering collection results. The following conventions are used:

  • order query string

    The order query string parameter specifies the attribute used to order the results. To return a collection in descending order, prefix the attribute with a minus sign ("-").

  • Multiple column ordering

    An operation may support ordering multiple columns in the order parameter by separating the columns with a comma. If an operation supports multiple columns, it treats the comma as a “THEN BY” directive. For example, order=dateTime,name indicates that the collection is sorted by dateTime then by name.

Filtering collections

Requests that are known to return a large number of items can be filtered using the filter query string parameter. The following SCIM protocol filtering operators are supported.

Operator Description Behavior
eq equal The attribute and operator values are not identical.
ne not equal The attribute and operator values must be identical for a match.
co contains The entire operator value must be a substring of the attribute value for a match.
sw starts with The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical.
ew ends with The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical.
pr present (has value) If the attribute has a non-empty or non-null value, or if it contains a non-empty node for complex attributes, there is a match.
gt greater than If the attribute value is greater than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
ge greater than or equal to If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
lt less than If the attribute value is less than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
le less than or equal to If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.

For more information about the SCIM Protocol Specification, see SCIM Filtering.

A particular operation may not support all SCIM filtering operators. In the event of a filtering operator not being supported, the operation will return 406 NOT ACCEPTABLE in the response.