Docs/API Reference

API Reference

The PermitNetworks REST API. All endpoints require authentication via API key.

Base URL: https://api.permitnetworks.com

Authentication

Pass your API key in the Authorization header on every request.

Authorization: Bearer pn_live_sk_7f3ae91c4b2d...

Submit an authorization request for a specific agent, action, and resource. The policy engine evaluates all matching policies in priority order and returns a decision. Under normal conditions, decisions are returned in under 1ms.

Parameters

Name	In	Type	Req	Description
`agent_id`	body	string	yes	Unique identifier for the agent requesting authorization. Must match the agentId used when initializing the SDK.
`action`	body	string	yes	The semantic action being requested (e.g. payment.create, data.read). Evaluated against policy action patterns.
`resource`	body	string	no	The target resource identifier (e.g. user:123, account:acct_9kx2m). Null if the action is not resource-specific.
`context`	body	object	no	Arbitrary key-value context used for condition evaluation. Values can be strings, numbers, booleans, or nested objects.

Response

{
  "id": "dec_01hwxyz1234567890abcdef",
  "effect": "allow",
  "reason": null,
  "policy_id": "pol_billing_payments",
  "agent_id": "billing-bot",
  "action": "payment.create",
  "resource": "account:acct_9kx2m",
  "latency_ms": 0.4,
  "evaluated_at": "2025-04-21T10:30:00.000Z",
  "expires_at": "2025-04-21T10:35:00.000Z",
  "permit_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

Example

curl -X POST https://api.permitnetworks.com/v1/decisions \
  -H "Authorization: Bearer pn_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "billing-bot",
    "action": "payment.create",
    "resource": "account:acct_9kx2m",
    "context": { "amount": 2500, "currency": "USD" }
  }'

HTTP Status Codes

Code	Meaning
200	Success
201	Created (POST /v1/policies)
400	Bad Request — malformed JSON or missing required field
401	Unauthorized — invalid or missing API key
403	Forbidden — API key lacks required scope
404	Not Found — resource does not exist
409	Conflict — policy with this name already exists
429	Rate Limited — retry after the Retry-After header value
500	Internal Server Error — contact support with request ID