Governance

Would this action be allowed, and what decides

REAL and PURE — no side effect, no ledger row, nothing enqueued, nothing metered, and side_effects: [] on the wire so a caller does not have to take the documentation’s word for it. The primitive tier is the GOVERNOR’s own verdict, over the same client the gate uses and with the same strict flag the gate would set for that primitive. The capability and approval tiers are re-derived, because the governor evaluates those inside a guarded evaluation that PERSISTS an approvals row when it freezes: an explain that called it would write one every time somebody asked a question. tiers names which is which, and which tiers (budget, freeze, connections, revocation, the actor test) this answer does not consult at all. A governor that is unreachable yields verdict: "unavailable" rather than the gate’s 403, because the endpoint you run to find out why you were refused cannot itself be refused.

POST

policy

explain

curl --request POST \
  --url https://api.usenaive.ai/v1/policy/explain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "<string>",
  "toolkit": "<string>",
  "payload": {}
}
'

import requests

url = "https://api.usenaive.ai/v1/policy/explain"

payload = {
    "action": "<string>",
    "toolkit": "<string>",
    "payload": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({action: '<string>', toolkit: '<string>', payload: {}})
};

fetch('https://api.usenaive.ai/v1/policy/explain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenaive.ai/v1/policy/explain",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => '<string>',
    'toolkit' => '<string>',
    'payload' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.usenaive.ai/v1/policy/explain"

	payload := strings.NewReader("{\n  \"action\": \"<string>\",\n  \"toolkit\": \"<string>\",\n  \"payload\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenaive.ai/v1/policy/explain")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"<string>\",\n  \"toolkit\": \"<string>\",\n  \"payload\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenaive.ai/v1/policy/explain")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"<string>\",\n  \"toolkit\": \"<string>\",\n  \"payload\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "action": "<string>",
  "tenant_user_id": "<string>",
  "environment": "<string>",
  "because": {
    "layer": "<string>",
    "rule": "<string>",
    "detail": "<string>"
  },
  "primitive": "<string>",
  "primitive_enabled": true,
  "capability_allowed": true,
  "requires_approval": true,
  "tiers": {},
  "side_effects": [
    "<string>"
  ]
}

{
  "error": {
    "message": "<string>",
    "hint": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "hint": "<string>",
    "reason": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Workspace API key. Create one via the dashboard or POST /v1/auth/keys.

Query Parameters

tenant

string

Tenant user id. Absent, the caller's own subject answers.

Body

application/json

action

string

required

Action id, e.g. "cards.create".

toolkit

string

For the connection family.

payload

object

Response

The verdict, and the layer and rule that produced it.

action

string

tenant_user_id

string

environment

string

verdict

enum<string>

The ENGINE's verdict vocabulary. approve is what a rule author writes; it folds to park.

Available options:

allow,

deny,

park,

attest,

unavailable

because

object

Show child attributes

primitive

string

primitive_enabled

boolean

capability_allowed

boolean

requires_approval

boolean

tiers

object

Which tiers this answer consulted (consulted), which it re-derived rather than asked the governor for (reimplemented), and which it did not evaluate at all (not_consulted). A caller that cannot tell those apart cannot judge how much to trust the verdict.

side_effects

string[]

Would this action be allowed, and what decides

curl --request POST \
  --url https://api.usenaive.ai/v1/policy/explain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "<string>",
  "toolkit": "<string>",
  "payload": {}
}
'

import requests

url = "https://api.usenaive.ai/v1/policy/explain"

payload = {
    "action": "<string>",
    "toolkit": "<string>",
    "payload": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({action: '<string>', toolkit: '<string>', payload: {}})
};

fetch('https://api.usenaive.ai/v1/policy/explain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenaive.ai/v1/policy/explain",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => '<string>',
    'toolkit' => '<string>',
    'payload' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.usenaive.ai/v1/policy/explain"

	payload := strings.NewReader("{\n  \"action\": \"<string>\",\n  \"toolkit\": \"<string>\",\n  \"payload\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenaive.ai/v1/policy/explain")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"<string>\",\n  \"toolkit\": \"<string>\",\n  \"payload\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenaive.ai/v1/policy/explain")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"<string>\",\n  \"toolkit\": \"<string>\",\n  \"payload\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "action": "<string>",
  "tenant_user_id": "<string>",
  "environment": "<string>",
  "because": {
    "layer": "<string>",
    "rule": "<string>",
    "detail": "<string>"
  },
  "primitive": "<string>",
  "primitive_enabled": true,
  "capability_allowed": true,
  "requires_approval": true,
  "tiers": {},
  "side_effects": [
    "<string>"
  ]
}

{
  "error": {
    "message": "<string>",
    "hint": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "hint": "<string>",
    "reason": "<string>"
  }
}