PingAuthorize API Reference

Statements

A statement is a directive that instructs the policy enforcement point (PEP) to perform additional actions alongside an authorization decision.

By adding statements to the Library, you can easily add them to your policies. Without statements, policies simply return a permit or deny decision. With statements, you can include additional information in decisions, such as adding response headers on a permit decision or including a message with a deny decision. Statements only apply when a rule or policy returns a permit or deny decision. They are not included in decisions that are indeterminate or not applicable.

The Policy Editor comes with the following pre-configured statements:

  • Add Filter: Use the add-filter code to add administrator-required filters to System for Cross-domain Identity Management (SCIM) search queries.

  • Combine SCIM Search Authorizations: Use the combine-scim-search-authorizations code to optimize policy processing for SCIM search responses.

  • Denied Reason: Use the denied-reason code to allow a policy writer to provide an error message that contains the reason for denying a request.

  • Exclude Attributes: Use the exclude-attributes code to specify the attributes to exclude from a JSON response.

  • Filter Response: Use the filter-response code to direct PingAuthorize Server to invoke policy iteratively over each item of a JSON array contained within an API response.

  • Include Attributes: Use the include-attributes code to limit the attributes that a JSON response can return.

  • Modify Attributes: Use the modify-attributes code to modify the values of attributes in the JSON request or response.

  • Modify Headers: Use the modify-headers code to modify the values of request headers before PingAuthorize sends them to the upstream server or to modify the values of response headers before PingAuthorize returns them to the client.

  • Modify Query: Use the modify-query to modify the query string of the request sent to the API server.

  • Modify SCIM Patch: Use the modify-scim-patch code to add operations to a SCIM patch in a modify request before it is submitted to the store adapter.

  • Regex Replace Attributes: Use the regex-replace-attributes to specify a regex to search for attributes in a request or response body and replace their values with a regex replacement string.

For more information about statement codes and payloads, refer to Statements in the PingAuthorize Policy Administration Guide.

The statements endpoint provides operations for creating, reading, updating, and deleting policy statements. Each operation requires either a branch ID or a statement ID in the request URL.

Statements data model

Property Type Required Mutable Description

id

String

N/A

Read-only

Specifies the ID of the statement.

version

String

N/A

Read-only

Specifies the version ID of the statement.

type

String

Optional

Mutable

Specifies the resource type. Always set to statement.

name

String

Required

Mutable

Specifies the name of the statement.

description

String

Optional

Mutable

Provides a description of the statement.

shared

Boolean

Optional

Mutable

A boolean that specifies whether or not the statement is shared between policy entities.

code

String

Required

Mutable

Specifies a unique statement type identifier.

appliesTo

String

Optional

Mutable

Specifies the type of decisions the statement is attached to. Allowable values are ANYTHING, PERMIT, DENY, PERMIT_OR_DENY, or INDETERMINATE. Defaults to ANYTHING.

appliesIf

String

Optional

Mutable

Specifies the condition under which the statement is returned in the decision response. Allowable values are ANYTHING, FINAL_DECISION_MATCHES, and PATH_MATCHES. Defaults to PATH_MATCHES.

payload

String

Optional

Mutable

Specifies the set of parameters governing the actions performed when PingAuthorize applies the statement. The appropriate payload value depends on the statement type.

obligatory

Boolean

Optional

Mutable

A boolean that determines whether the final decision applies only if the statement can be fulfilled.

attributes

String[]

Optional

Mutable

Specifies the IDs of attributes to include in the statement payload.

services

String[]

Optional

Mutable

Specifies the IDs of services to include in the statement payload.

effectivePermissions

JSON[]

N/A

Read-only

Specifies a list of permissions assigned to the statement. Each permission object contains the following fields:
* permission: The operation for which permission is enabled. For example, READ.
* role: The role to which the permission is assigned.

definedOn

String

N/A

Read-only

Specifies the unique ID of the statement to which permissions are assigned.

inherited

Boolean

N/A

Read-only

Specifies whether or not permissions are inherited from a parent entity.

pageHeader.entityId

UUID

N/A

Read-only

Specifies the unique ID of the statement for which a version history is being retrieved.

pageHeader.entityType

String

N/A

Read-only

Specifies the type of entity for which a version history is being retrieved.

version

UUID

N/A

Read-only

Specifies the unique ID of a statement version.

deltaId

UUID

N/A

Read-only

Specifies the unique ID of a snapshot delta.

snapshotId

UUID

N/A

Read-only

Specifies the unique ID of a snapshot.

timestamp

String

N/A

Read-only

Specifies the date and time at which a delta was generated.

user

String

N/A

Read-only

Specifies the user who was signed when the delta was generated.

If the appliesTo criteria for a statement is met by its associated rule or policy decision, and that decision contributes to the final result, PingAuthorize uses the statement in its final response if the statement’s associated appliesIf condition is satisfied.

Result filtering data model

Filtering parameter Description

page

Specifies the page number of results to return.

page-size

Specifies the number of results to return per page.

onlyShared

Set to true to only list the statements shared between policy entities. Set to false to list all statements defined in the system.

Response codes

Code Message

200

Successful operation.

201

Successful operation.

400

A branch, snapshot or JSON value has not been specified correctly, or is missing.

404

The statement with the given ID was not found.

409

The statement ID in the URL does not match the statement ID in the request body.

409

The statement is referred to somewhere else and cannot be deleted until those references are removed.