PingAuthorize API Reference

Query Decision Request

POST {{apiPath}}/governance-engine/query

The POST /governance-engine/query operation allows you to make open ended decision requests that give you information about what is authorized within a given context. For example, you could obtain information about what actions users are authorized to perform on a particular account.

In the request body:

The query value is an array that contains the following properties:

  • attribute: The full name of an unbounded, multivalued, or single-valued attribute.

    Below is a description of the attribute types:

    • Unbounded: When an attribute is provided in the query, but the values property is omitted. The attribute’s values are obtained from Query Source.

    • Multivalued: When an attribute is provided in the query and the values array contains more than one value. Values could be obtained from Query Source when the values property is omitted, or directly from the values array if the values are provided in the request.

    • Single-valued: When an attribute is provided in the query and the values array contains a single-value.

    At most, two attributes in the query array can be unbounded. Up to three attributes can be multivalued.

    Attributes can be used to resolve other attributes. For example, if you have included two attributes in the array, you can use one of these attributes to resolve the other, or vice versa.

    Learn more about the supported query attribute combinations in the Policy queries section in the PingAuthorize admin documentation.

  • values: An optional array defining the values of the attribute.

    If you include more than one value in this array, the JSON PDP API treats the attribute as multivalued. If the attribute is unbounded, this array is not required.

  • context: A JSON object containing the fields included in a typical individual JSON PDP API request.

In the request response, the results array contains a list of query attribute values that either produced a PERMIT decision result or a DENY decision result with statements.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Accept      application/json

Body

raw ( application/json )

{
  "query": [
    {
      "attribute": "user",
      "values": [
        "{\"id\":1}",
        "{\"id\":2}"
      ]
    },
    {
      "attribute": "action",
      "values": [
        "read"
      ]
    },
    {
      "attribute": "account"
    }
  ],
  "context": {
    "domain": "",
    "service": "",
    "identityProvider": "",
    "action": "",
    "attributes": {
      "environment": "PROD",
      "correlationId": {{correlationId}}
    }
  }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/governance-engine/query' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
  "query": [
    {
      "attribute": "user",
      "values": [
        "{\"id\":1}",
        "{\"id\":2}"
      ]
    },
    {
      "attribute": "action",
      "values": [
        "read"
      ]
    },
    {
      "attribute": "account"
    }
  ],
  "context": {
    "domain": "",
    "service": "",
    "identityProvider": "",
    "action": "",
    "attributes": {
      "environment": "PROD",
      "correlationId": {{correlationId}}
    }
  }
}'
var options = new RestClientOptions("{{apiPath}}/governance-engine/query")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"  ""query"": [" + "\n" +
@"    {" + "\n" +
@"      ""attribute"": ""user""," + "\n" +
@"      ""values"": [" + "\n" +
@"        ""{\""id\"":1}""," + "\n" +
@"        ""{\""id\"":2}""" + "\n" +
@"      ]" + "\n" +
@"    }," + "\n" +
@"    {" + "\n" +
@"      ""attribute"": ""action""," + "\n" +
@"      ""values"": [" + "\n" +
@"        ""read""" + "\n" +
@"      ]" + "\n" +
@"    }," + "\n" +
@"    {" + "\n" +
@"      ""attribute"": ""account""" + "\n" +
@"    }" + "\n" +
@"  ]," + "\n" +
@"  ""context"": {" + "\n" +
@"    ""domain"": """"," + "\n" +
@"    ""service"": """"," + "\n" +
@"    ""identityProvider"": """"," + "\n" +
@"    ""action"": """"," + "\n" +
@"    ""attributes"": {" + "\n" +
@"      ""environment"": ""PROD""," + "\n" +
@"      ""correlationId"": {{correlationId}}" + "\n" +
@"    }" + "\n" +
@"  }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

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

func main() {

  url := "{{apiPath}}/governance-engine/query"
  method := "POST"

  payload := strings.NewReader(`{
  "query": [
    {
      "attribute": "user",
      "values": [
        "{\"id\":1}",
        "{\"id\":2}"
      ]
    },
    {
      "attribute": "action",
      "values": [
        "read"
      ]
    },
    {
      "attribute": "account"
    }
  ],
  "context": {
    "domain": "",
    "service": "",
    "identityProvider": "",
    "action": "",
    "attributes": {
      "environment": "PROD",
      "correlationId": {{correlationId}}
    }
  }
}`)

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

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  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))
}
POST /governance-engine/query HTTP/1.1
Host: {{apiPath}}
Accept: application/json
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
  "query": [
    {
      "attribute": "user",
      "values": [
        "{\"id\":1}",
        "{\"id\":2}"
      ]
    },
    {
      "attribute": "action",
      "values": [
        "read"
      ]
    },
    {
      "attribute": "account"
    }
  ],
  "context": {
    "domain": "",
    "service": "",
    "identityProvider": "",
    "action": "",
    "attributes": {
      "environment": "PROD",
      "correlationId": {{correlationId}}
    }
  }
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"query\": [\n    {\n      \"attribute\": \"user\",\n      \"values\": [\n        \"{\\\"id\\\":1}\",\n        \"{\\\"id\\\":2}\"\n      ]\n    },\n    {\n      \"attribute\": \"action\",\n      \"values\": [\n        \"read\"\n      ]\n    },\n    {\n      \"attribute\": \"account\"\n    }\n  ],\n  \"context\": {\n    \"domain\": \"\",\n    \"service\": \"\",\n    \"identityProvider\": \"\",\n    \"action\": \"\",\n    \"attributes\": {\n      \"environment\": \"PROD\",\n      \"correlationId\": {{correlationId}}\n    }\n  }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/governance-engine/query")
  .method("POST", body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/governance-engine/query",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": "{\n  \"query\": [\n    {\n      \"attribute\": \"user\",\n      \"values\": [\n        \"{\\\"id\\\":1}\",\n        \"{\\\"id\\\":2}\"\n      ]\n    },\n    {\n      \"attribute\": \"action\",\n      \"values\": [\n        \"read\"\n      ]\n    },\n    {\n      \"attribute\": \"account\"\n    }\n  ],\n  \"context\": {\n    \"domain\": \"\",\n    \"service\": \"\",\n    \"identityProvider\": \"\",\n    \"action\": \"\",\n    \"attributes\": {\n      \"environment\": \"PROD\",\n      \"correlationId\": {{correlationId}}\n    }\n  }\n}",
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/governance-engine/query',
  'headers': {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: '{\n  "query": [\n    {\n      "attribute": "user",\n      "values": [\n        "{\\"id\\":1}",\n        "{\\"id\\":2}"\n      ]\n    },\n    {\n      "attribute": "action",\n      "values": [\n        "read"\n      ]\n    },\n    {\n      "attribute": "account"\n    }\n  ],\n  "context": {\n    "domain": "",\n    "service": "",\n    "identityProvider": "",\n    "action": "",\n    "attributes": {\n      "environment": "PROD",\n      "correlationId": {{correlationId}}\n    }\n  }\n}'

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/governance-engine/query"

payload = "{\n  \"query\": [\n    {\n      \"attribute\": \"user\",\n      \"values\": [\n        \"{\\\"id\\\":1}\",\n        \"{\\\"id\\\":2}\"\n      ]\n    },\n    {\n      \"attribute\": \"action\",\n      \"values\": [\n        \"read\"\n      ]\n    },\n    {\n      \"attribute\": \"account\"\n    }\n  ],\n  \"context\": {\n    \"domain\": \"\",\n    \"service\": \"\",\n    \"identityProvider\": \"\",\n    \"action\": \"\",\n    \"attributes\": {\n      \"environment\": \"PROD\",\n      \"correlationId\": {{correlationId}}\n    }\n  }\n}"
headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

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

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/governance-engine/query');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Accept' => 'application/json',
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n  "query": [\n    {\n      "attribute": "user",\n      "values": [\n        "{\\"id\\":1}",\n        "{\\"id\\":2}"\n      ]\n    },\n    {\n      "attribute": "action",\n      "values": [\n        "read"\n      ]\n    },\n    {\n      "attribute": "account"\n    }\n  ],\n  "context": {\n    "domain": "",\n    "service": "",\n    "identityProvider": "",\n    "action": "",\n    "attributes": {\n      "environment": "PROD",\n      "correlationId": {{correlationId}}\n    }\n  }\n}');
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 "json"
require "net/http"

url = URI("{{apiPath}}/governance-engine/query")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = "{\n  \"query\": [\n    {\n      \"attribute\": \"user\",\n      \"values\": [\n        \"{\\\"id\\\":1}\",\n        \"{\\\"id\\\":2}\"\n      ]\n    },\n    {\n      \"attribute\": \"action\",\n      \"values\": [\n        \"read\"\n      ]\n    },\n    {\n      \"attribute\": \"account\"\n    }\n  ],\n  \"context\": {\n    \"domain\": \"\",\n    \"service\": \"\",\n    \"identityProvider\": \"\",\n    \"action\": \"\",\n    \"attributes\": {\n      \"environment\": \"PROD\",\n      \"correlationId\": {{correlationId}}\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
let parameters = "{\n  \"query\": [\n    {\n      \"attribute\": \"user\",\n      \"values\": [\n        \"{\\\"id\\\":1}\",\n        \"{\\\"id\\\":2}\"\n      ]\n    },\n    {\n      \"attribute\": \"action\",\n      \"values\": [\n        \"read\"\n      ]\n    },\n    {\n      \"attribute\": \"account\"\n    }\n  ],\n  \"context\": {\n    \"domain\": \"\",\n    \"service\": \"\",\n    \"identityProvider\": \"\",\n    \"action\": \"\",\n    \"attributes\": {\n      \"environment\": \"PROD\",\n      \"correlationId\": {{correlationId}}\n    }\n  }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/governance-engine/query")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Accept")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

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

{
    "requestId": "4ec1b233-41ab-4656-a9ae-254da30a933d",
    "timeStamp": "2024-06-18T09:35:44.228951Z",
    "deploymentPackageId": "91b29834-3f6f-48cd-912a-5a1014922946",
    "elapsedTime": 29,
    "results": [
        {
            "attribute": "user",
            "value": "{\"id\":1}",
            "results": [
                {
                    "attribute": "action",
                    "value": "read",
                    "results": [
                        {
                            "attribute": "account",
                            "value": "{\"ownerId\":1}",
                            "decision": "PERMIT"
                        }
                    ]
                }
            ]
        },
        {
            "attribute": "user",
            "value": "{\"id\":2}",
            "results": [
                {
                    "attribute": "action",
                    "value": "read",
                    "results": [
                        {
                            "attribute": "account",
                            "value": "{\"ownerId\":2}",
                            "decision": "PERMIT"
                        }
                    ]
                }
            ]
        }
    ]
}