Propose granting or revoking an agent's authority

POST

authority-grants

changes

cURL

curl -X POST https://parmana-api-real.vercel.app/authority-grants/changes \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "grant",
    "callerId": "warehouse-agent",
    "capability": "erp:release-goods",
    "limits": {
      "parameters.amount": { "max": 100000 },
      "parameters.currency": { "oneOf": ["INR"] }
    },
    "validUntil": "2026-12-30T00:00:00.000Z",
    "reason": "The warehouse agent releases goods for paid invoices up to 100000 INR this quarter."
  }'

import { ParmanaClient } from "@parmana/sdk";

const client = new ParmanaClient({
  endpoint: "https://parmana-api-real.vercel.app",
  apiKey: process.env.PARMANA_API_KEY!,
});

const change = await client.proposeAuthorityGrantChange({
  action: "grant",
  callerId: "warehouse-agent",
  capability: "erp:release-goods",
  limits: {
    "parameters.amount": { max: 100000 },
    "parameters.currency": { oneOf: ["INR"] },
  },
  validUntil: "2026-12-30T00:00:00.000Z",
  reason:
    "The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.",
});

console.log(change.changeId);

import os

from parmana import ParmanaClient

client = ParmanaClient(
    endpoint="https://parmana-api-real.vercel.app",
    api_key=os.environ["PARMANA_API_KEY"],
)

change = client.authority_grants.propose_grant(
    caller_id="warehouse-agent",
    capability="erp:release-goods",
    limits={
        "parameters.amount": {"max": 100000},
        "parameters.currency": {"oneOf": ["INR"]},
    },
    valid_until="2026-12-30T00:00:00.000Z",
    reason=(
        "The warehouse agent releases goods for paid invoices up to 100000 INR "
        "this quarter."
    ),
)

print(change.change_id)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: 'grant',
    callerId: 'warehouse-agent',
    capability: 'erp:release-goods',
    limits: {'parameters.amount': {max: 100000}, 'parameters.currency': {oneOf: ['INR']}},
    validUntil: '2026-12-30T00:00:00.000Z',
    reason: 'The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.'
  })
};

fetch('https://parmana-sandbox.vercel.app/authority-grants/changes', 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://parmana-sandbox.vercel.app/authority-grants/changes",
  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' => 'grant',
    'callerId' => 'warehouse-agent',
    'capability' => 'erp:release-goods',
    'limits' => [
        'parameters.amount' => [
                'max' => 100000
        ],
        'parameters.currency' => [
                'oneOf' => [
                                'INR'
                ]
        ]
    ],
    'validUntil' => '2026-12-30T00:00:00.000Z',
    'reason' => 'The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.'
  ]),
  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://parmana-sandbox.vercel.app/authority-grants/changes"

	payload := strings.NewReader("{\n  \"action\": \"grant\",\n  \"callerId\": \"warehouse-agent\",\n  \"capability\": \"erp:release-goods\",\n  \"limits\": {\n    \"parameters.amount\": {\n      \"max\": 100000\n    },\n    \"parameters.currency\": {\n      \"oneOf\": [\n        \"INR\"\n      ]\n    }\n  },\n  \"validUntil\": \"2026-12-30T00:00:00.000Z\",\n  \"reason\": \"The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.\"\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://parmana-sandbox.vercel.app/authority-grants/changes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"grant\",\n  \"callerId\": \"warehouse-agent\",\n  \"capability\": \"erp:release-goods\",\n  \"limits\": {\n    \"parameters.amount\": {\n      \"max\": 100000\n    },\n    \"parameters.currency\": {\n      \"oneOf\": [\n        \"INR\"\n      ]\n    }\n  },\n  \"validUntil\": \"2026-12-30T00:00:00.000Z\",\n  \"reason\": \"The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://parmana-sandbox.vercel.app/authority-grants/changes")

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\": \"grant\",\n  \"callerId\": \"warehouse-agent\",\n  \"capability\": \"erp:release-goods\",\n  \"limits\": {\n    \"parameters.amount\": {\n      \"max\": 100000\n    },\n    \"parameters.currency\": {\n      \"oneOf\": [\n        \"INR\"\n      ]\n    }\n  },\n  \"validUntil\": \"2026-12-30T00:00:00.000Z\",\n  \"reason\": \"The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.\"\n}"

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

{
  "changeId": "9f3cf733-a8ed-487c-bb58-a53950388cdf",
  "action": "grant",
  "callerId": "warehouse-agent",
  "capability": "erp:release-goods",
  "limits": {
    "parameters.amount": {
      "max": 100000
    },
    "parameters.currency": {
      "oneOf": [
        "INR"
      ]
    }
  },
  "validUntil": "2026-12-30T00:00:00.000Z",
  "reason": "The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.",
  "proposedBy": "grant-maker",
  "proposedAt": "2026-10-11T03:29:05.220Z",
  "status": "PENDING_APPROVAL"
}

Authorizations

Authorization

string

header

default:2VfYWCzt_cBAPK-8uufX6ordfY2JuQhFPsohuEumKME

required

Caller API key issued by scripts/generate-api-key.ts. Sent as Authorization: Bearer . Verified against a stored SHA-256 hash in constant time by packages/api/src/auth/StaticKeyAuthenticator.ts. Required on every route not listed as exempt in this document's top-level description. See /api-reference/authentication.

Body

application/json

Request body for POST /authority-grants/changes. A grant carries validUntil and optionally limits and validFrom; a revoke carries none of them.

action

enum<string>

required

Available options:

grant,

revoke

callerId

string

required

The callerId of the API key the grant is for. Not your own.

Pattern: ^\S{1,256}$

capability

string

required

Maximum string length: 128

Pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*:[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$

reason

string

required

Required string length: 1 - 2000

limits

object

Optional, grant only. Limits on the request, by Intent path: target or parameters.. min and max (inclusive) apply to a number there; oneOf lists the only values allowed there. A request whose value is missing, of another type, or outside a limit is NOT_AUTHORIZED.

Show child attributes

validFrom

string<date-time>

Optional, grant only.

validUntil

string<date-time>

Required for grant. In the future, after validFrom, and at most 366 days after it.

Response

Proposed and waiting for a checker. Keep the changeId.

Response of POST /authority-grants/changes (201) and of approve and reject (200). A bare Authority Grant Change, no wrapper.

changeId

string

required

Unique id of the change, a UUID. The step up authorization for approve or reject names it in payload.pendingPolicyChangeId. An approved grant change's id is also the grantId.

action

enum<string>

required

Available options:

grant,

revoke

callerId

string

required

capability

string

required

Pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*:[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$

reason

string

required

Maximum string length: 2000

proposedBy

string

required

The proposer's caller id. Always a human credential, never the grantee.

proposedAt

string<date-time>

required

status

enum<string>

required

Available options:

PENDING_APPROVAL,

APPROVED,

REJECTED

limits

object

grant only, optional. Limits on the request, by Intent path: target or parameters.. min and max (inclusive) apply to a number there; oneOf lists the only values allowed there. A request whose value is missing, of another type, or outside a limit is NOT_AUTHORIZED.

Show child attributes

validFrom

string<date-time>

grant only, optional. Without it the grant starts when it is approved.

validUntil

string<date-time>

grant only, required. At most 366 days after validFrom (or the proposal).

resolvedBy

string

Who approved or rejected it. Never the proposer or the grantee.

resolvedAt

string<date-time>

rejectionReason

string

Present when REJECTED.

cURL

curl -X POST https://parmana-api-real.vercel.app/authority-grants/changes \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "grant",
    "callerId": "warehouse-agent",
    "capability": "erp:release-goods",
    "limits": {
      "parameters.amount": { "max": 100000 },
      "parameters.currency": { "oneOf": ["INR"] }
    },
    "validUntil": "2026-12-30T00:00:00.000Z",
    "reason": "The warehouse agent releases goods for paid invoices up to 100000 INR this quarter."
  }'

import { ParmanaClient } from "@parmana/sdk";

const client = new ParmanaClient({
  endpoint: "https://parmana-api-real.vercel.app",
  apiKey: process.env.PARMANA_API_KEY!,
});

const change = await client.proposeAuthorityGrantChange({
  action: "grant",
  callerId: "warehouse-agent",
  capability: "erp:release-goods",
  limits: {
    "parameters.amount": { max: 100000 },
    "parameters.currency": { oneOf: ["INR"] },
  },
  validUntil: "2026-12-30T00:00:00.000Z",
  reason:
    "The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.",
});

console.log(change.changeId);

import os

from parmana import ParmanaClient

client = ParmanaClient(
    endpoint="https://parmana-api-real.vercel.app",
    api_key=os.environ["PARMANA_API_KEY"],
)

change = client.authority_grants.propose_grant(
    caller_id="warehouse-agent",
    capability="erp:release-goods",
    limits={
        "parameters.amount": {"max": 100000},
        "parameters.currency": {"oneOf": ["INR"]},
    },
    valid_until="2026-12-30T00:00:00.000Z",
    reason=(
        "The warehouse agent releases goods for paid invoices up to 100000 INR "
        "this quarter."
    ),
)

print(change.change_id)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: 'grant',
    callerId: 'warehouse-agent',
    capability: 'erp:release-goods',
    limits: {'parameters.amount': {max: 100000}, 'parameters.currency': {oneOf: ['INR']}},
    validUntil: '2026-12-30T00:00:00.000Z',
    reason: 'The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.'
  })
};

fetch('https://parmana-sandbox.vercel.app/authority-grants/changes', 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://parmana-sandbox.vercel.app/authority-grants/changes",
  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' => 'grant',
    'callerId' => 'warehouse-agent',
    'capability' => 'erp:release-goods',
    'limits' => [
        'parameters.amount' => [
                'max' => 100000
        ],
        'parameters.currency' => [
                'oneOf' => [
                                'INR'
                ]
        ]
    ],
    'validUntil' => '2026-12-30T00:00:00.000Z',
    'reason' => 'The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.'
  ]),
  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://parmana-sandbox.vercel.app/authority-grants/changes"

	payload := strings.NewReader("{\n  \"action\": \"grant\",\n  \"callerId\": \"warehouse-agent\",\n  \"capability\": \"erp:release-goods\",\n  \"limits\": {\n    \"parameters.amount\": {\n      \"max\": 100000\n    },\n    \"parameters.currency\": {\n      \"oneOf\": [\n        \"INR\"\n      ]\n    }\n  },\n  \"validUntil\": \"2026-12-30T00:00:00.000Z\",\n  \"reason\": \"The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.\"\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://parmana-sandbox.vercel.app/authority-grants/changes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"grant\",\n  \"callerId\": \"warehouse-agent\",\n  \"capability\": \"erp:release-goods\",\n  \"limits\": {\n    \"parameters.amount\": {\n      \"max\": 100000\n    },\n    \"parameters.currency\": {\n      \"oneOf\": [\n        \"INR\"\n      ]\n    }\n  },\n  \"validUntil\": \"2026-12-30T00:00:00.000Z\",\n  \"reason\": \"The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://parmana-sandbox.vercel.app/authority-grants/changes")

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\": \"grant\",\n  \"callerId\": \"warehouse-agent\",\n  \"capability\": \"erp:release-goods\",\n  \"limits\": {\n    \"parameters.amount\": {\n      \"max\": 100000\n    },\n    \"parameters.currency\": {\n      \"oneOf\": [\n        \"INR\"\n      ]\n    }\n  },\n  \"validUntil\": \"2026-12-30T00:00:00.000Z\",\n  \"reason\": \"The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.\"\n}"

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

{
  "changeId": "9f3cf733-a8ed-487c-bb58-a53950388cdf",
  "action": "grant",
  "callerId": "warehouse-agent",
  "capability": "erp:release-goods",
  "limits": {
    "parameters.amount": {
      "max": 100000
    },
    "parameters.currency": {
      "oneOf": [
        "INR"
      ]
    }
  },
  "validUntil": "2026-12-30T00:00:00.000Z",
  "reason": "The warehouse agent releases goods for paid invoices up to 100000 INR this quarter.",
  "proposedBy": "grant-maker",
  "proposedAt": "2026-10-11T03:29:05.220Z",
  "status": "PENDING_APPROVAL"
}

REST API guide

Execution

Transactions

Verification

Receipts

Trust Records

Replay

Policies

Policy Governance

Approvers

External Connectors

Business Signal Sources

Authority Grants

Sandbox

Refusal Records

Execution Intents

Audit

System

Handbook

Propose granting or revoking an agent's authority

Authorizations

Body

Response