PingAuthorize API Reference

Read All Statements

GET {{apiPath}}/v2/policy-manager/statements?branch={{branchId}}

The GET /v2/policy-manager/statements operation returns a list of all statements defined on a specified Policy Editor branch. The request must provide either a branch ID or a snapshot ID in the request URL to specify where the statements should be read from.

Prerequisites

Query parameters
Query parameter Description

branch

Branch ID or name.

snapshot

Snapshot ID.

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.

Headers

x-user-id      {{userId}}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}' \
--header 'x-user-id: {{userId}}'
var options = new RestClientOptions("{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Get);
request.AddHeader("x-user-id", "{{userId}}");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("x-user-id", "{{userId}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
GET /v2/policy-manager/statements?branch={{branchId}} HTTP/1.1
Host: {{apiPath}}
x-user-id: {{userId}}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}")
  .method("GET", body)
  .addHeader("x-user-id", "{{userId}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "x-user-id": "{{userId}}"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'GET',
  'url': '{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}',
  'headers': {
    'x-user-id': '{{userId}}'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests

url = "{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}"

payload = {}
headers = {
  'x-user-id': '{{userId}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'x-user-id' => '{{userId}}'
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "net/http"

url = URI("{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["x-user-id"] = "{{userId}}"

response = http.request(request)
puts response.read_body
var request = URLRequest(url: URL(string: "{{apiPath}}/v2/policy-manager/statements?branch={{branchId}}")!,timeoutInterval: Double.infinity)
request.addValue("{{userId}}", forHTTPHeaderField: "x-user-id")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

200 OK

{
    "pagination": {
        "page": 1,
        "pageSize": 100,
        "totalItems": 13,
        "totalPages": 1
    },
    "data": [
        {
            "id": "0015204d-7643-43ba-bbcb-23c5351fd6dc",
            "version": "1cef1423-60f3-40e2-8c77-96767a3f281e",
            "type": "Statement",
            "name": "example-statement",
            "description": "Example denial statement",
            "shared": true,
            "code": "denied-reason",
            "appliesTo": "DENY",
            "appliesIf": "PATH_MATCHES",
            "payload": "Requested operation not allowed by the granted OAuth scopes.",
            "obligatory": false,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "1c93ee51-44ec-4ad3-8bee-bc3f58a06b15",
            "version": "196a2680-0f94-40f2-ae55-d099f6035f7b",
            "type": "Statement",
            "name": "Exclude private data",
            "description": "",
            "shared": false,
            "code": "exclude-attributes",
            "appliesTo": "ANYTHING",
            "appliesIf": "PATH_MATCHES",
            "payload": "[\"data.private\"]",
            "obligatory": false,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "1fc6090f-bae7-457e-87b2-828d97578879",
            "version": "5d086083-8296-4dbe-8af9-aeb48b25d7a9",
            "type": "Statement",
            "name": "Include all attributes",
            "description": "Allows a client to read any attribute.",
            "shared": true,
            "code": "include-attributes",
            "appliesTo": "PERMIT",
            "appliesIf": "PATH_MATCHES",
            "payload": "[\"*\"]",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "51119f2f-ab5b-4184-8108-53daeceb834f",
            "version": "3706b0e3-4057-4597-8d36-0f3a365832bb",
            "type": "Statement",
            "name": "Include attributes permitted by scope",
            "description": "",
            "shared": false,
            "code": "include-attributes",
            "appliesTo": "PERMIT",
            "appliesIf": "PATH_MATCHES",
            "payload": "[\"CHANGEME\"]",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "9d51f642-74d0-402b-9352-be5c97e16619",
            "version": "b89f30e8-e1b5-4a3b-bba9-526993d09f47",
            "type": "Statement",
            "name": "Include email attributes",
            "description": "Allows to read specific email address attributes. Note that these attributes are schema-specific and may need to be changed to reflect your user schema.",
            "shared": true,
            "code": "include-attributes",
            "appliesTo": "PERMIT",
            "appliesIf": "PATH_MATCHES",
            "payload": "[\"mail\"]",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "c5a3b0f7-0094-4c76-9ffe-bbffe99becc8",
            "version": "ca4a7966-ea2c-4d7a-99d0-72dce415fef0",
            "type": "Statement",
            "name": "Include profile attributes",
            "description": "Allows a client to read a set of specific user profile attributes. Note that these attributes are schema-specific and may need to be changed to reflect your user schema.",
            "shared": true,
            "code": "include-attributes",
            "appliesTo": "PERMIT",
            "appliesIf": "PATH_MATCHES",
            "payload": "[\"uid\", \"sn\", \"givenName\", \"description\"]",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "d14656f2-4c95-420d-913d-a67d9bf3e10d",
            "version": "68f315c0-f105-4eb5-b13b-2da56a99412d",
            "type": "Statement",
            "name": "Insufficient Scope",
            "description": "For use when a policy denies a request because the bearer token scopes do not authorize the client to access the requested resource.",
            "shared": true,
            "code": "denied-reason",
            "appliesTo": "DENY",
            "appliesIf": "PATH_MATCHES",
            "payload": "{\"status\":403, \"message\":\"insufficient_scope\", \"detail\":\"Requested operation not allowed by the granted OAuth scopes.\"}",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "cde26a38-2035-4385-bbfe-159ee1822976",
            "version": "f0ac1ef7-0895-492e-b341-ee11d7d30bd0",
            "type": "Statement",
            "name": "Invalid Token",
            "description": "For use when a policy denies a request because the access token is inactive, expired, or otherwise invalid.",
            "shared": true,
            "code": "denied-reason",
            "appliesTo": "DENY",
            "appliesIf": "PATH_MATCHES",
            "payload": "{\"status\":401, \"message\": \"invalid_token\", \"detail\":\"Access token is expired or otherwise invalid\"}",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "eb5d1a2d-1dfb-4318-9fd8-fbe8bec7eb30",
            "version": "47b22b46-8b39-4bcc-b309-d8450e93578c",
            "type": "Statement",
            "name": "Optimize SCIM searches",
            "description": "When included in the decision for a SCIM2 policy request with the 'search' action, directs the PingAuthorize to authorize and filter search results using a single policy request with the 'search-results' action. This advice type does not require a payload.",
            "shared": true,
            "code": "combine-scim-search-authorizations",
            "appliesTo": "PERMIT",
            "appliesIf": "PATH_MATCHES",
            "payload": "",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "0c800787-e5ac-47ad-8a8c-d687328ab5d6",
            "version": "5c8bc0a3-117c-4d0e-8e3a-24c43581b702",
            "type": "Statement",
            "name": "Restrict attributes visible to interns",
            "description": "",
            "shared": false,
            "code": "exclude-attributes",
            "appliesTo": "PERMIT",
            "appliesIf": "PATH_MATCHES",
            "payload": "[\"description\"]",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "69c27fb8-ea1a-483a-9963-5af068f5130e",
            "version": "c37c4161-574b-40a7-936b-92ce3a368f68",
            "type": "Statement",
            "name": "Send \"not permitted\" error",
            "description": "Advice that allows a policy writer to provide an error message containing the reason that a request has been denied.",
            "shared": false,
            "code": "denied-reason",
            "appliesTo": "DENY",
            "appliesIf": "PATH_MATCHES",
            "payload": "{\"status\": 451, \"message\": \"Restricted\", \"detail\": \"Not permitted per regulation\"}",
            "obligatory": false,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "c4ac0c82-9d22-492f-b36c-9aa56f6f3161",
            "version": "6138fa93-6284-40e7-b629-ab9399d308ee",
            "type": "Statement",
            "name": "Unauthorized Audience",
            "description": "For use when a policy denies a request because the access token audience is incorrect for the requested service.",
            "shared": true,
            "code": "denied-reason",
            "appliesTo": "DENY",
            "appliesIf": "PATH_MATCHES",
            "payload": " {\"status\":403, \"message\":\"invalid_token\", \"detail\":\"The access token was issued for a different audience.\"}",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        },
        {
            "id": "76295749-1b58-40c3-9b14-9eceeb6d5a79",
            "version": "c5fc99cb-1a88-4318-b896-c44fedd668eb",
            "type": "Statement",
            "name": "Unauthorized Client",
            "description": "For use when a policy denies a request because the client is not authorized to access the requested resource.",
            "shared": true,
            "code": "denied-reason",
            "appliesTo": "DENY",
            "appliesIf": "PATH_MATCHES",
            "payload": " {\"status\":401,\"detail\":\"unauthorized_client\",\"message\":\"The client is not authorized to request this resource.\"}",
            "obligatory": true,
            "permissions": {
                "inherit": true,
                "rolePermissions": []
            },
            "attributes": [],
            "services": []
        }
    ]
}