5-Minute Quickstart
Go from zero to authorized in under 5 minutes. By the end of this guide you will have installed the SDK, created an API key, and received your first allow/deny decision from PermitNetworks.
Install the SDK
Install the PermitNetworks SDK for your language. TypeScript and Python are stable; Rust is in beta.
npm install @permitnetworks/sdkpip install permitnetworksRequires Node.js 18+ or Python 3.10+. The SDK ships TypeScript types — no separate @types package needed.
Get Your API Key
Log in to your dashboard and navigate to Dashboard → API Keys. Create a key scoped to your environment.
# Test environment (safe for development) PERMIT_API_KEY=pn_test_sk_7f3ae91c4b2d... # Production (keep this secret — never commit) PERMIT_API_KEY=pn_live_sk_8a1bc09d3e4f...
Test keys (pn_test_sk_) are rate-limited to 500 req/min and decisions are not billed. Live keys are required for production workloads.
Initialize the Client
Create a PermitClient instance. A single instance is safe to reuse across your entire application — the SDK manages connection pooling internally.
import { PermitClient } from "@permitnetworks/sdk";
const permit = new PermitClient({
apiKey: process.env.PERMIT_API_KEY!,
agentId: "my-first-agent", // unique ID for this agent
// pdp: "https://api.permitnetworks.com", // default
// timeout: 2000, // ms, default 2000
});from permitnetworks import PermitClient
import os
permit = PermitClient(
api_key=os.environ["PERMIT_API_KEY"],
agent_id="my-first-agent",
)Request Your First Authorization
Call permit.authorize() before every sensitive operation. The SDK evaluates your policies and returns a decision in under 1ms from the nearest edge node.
import { PermitClient } from "@permitnetworks/sdk";
const permit = new PermitClient({
apiKey: process.env.PERMIT_API_KEY!,
agentId: "my-first-agent",
});
// Request authorization for an action
const decision = await permit.authorize({
action: "data.read",
resource: "user:123",
// Optional: pass context for condition evaluation
context: {
ip: "203.0.113.42",
environment: "production",
},
});
if (decision.effect === "allow") {
console.log("Authorized. Decision ID:", decision.id);
// Proceed with the operation
const data = await fetchUserData("123");
// Optionally confirm the action completed
await permit.confirm(decision.id);
} else {
console.log("Denied:", decision.reason);
// decision.reason: "rate_limit.exceeded" | "policy.deny" | ...
throw new Error(`Unauthorized: ${decision.reason}`);
}Expected Output
A successful allow decision looks like this:
{
"id": "dec_01hwxyz1234567890abcdef",
"effect": "allow",
"reason": null,
"policy_id": "pol_billing_read",
"agent_id": "my-first-agent",
"action": "data.read",
"resource": "user:123",
"latency_ms": 0.4,
"evaluated_at": "2025-04-21T10:30:00.000Z",
"expires_at": "2025-04-21T10:35:00.000Z"
}A deny decision returns effect: "deny" and a machine-readable reason string. See the Error Codes reference for all possible reasons.
Verify with curl
You can also test authorization directly without any SDK:
curl -X POST https://api.permitnetworks.com/v1/decisions \
-H "Authorization: Bearer pn_test_sk_..." \
-H "Content-Type: application/json" \
-d '{
"agent_id": "my-first-agent",
"action": "data.read",
"resource": "user:123"
}'Common Errors
auth.invalid_keyHTTP 401API key is malformed or does not exist.
Fix: Check that PERMIT_API_KEY is set correctly and the key was not revoked in the dashboard.
policy.not_foundHTTP 200 (deny)No policy matched the agent + action + resource combination.
Fix: Create a policy in the dashboard for this agent. Without a matching policy, all requests are denied by default.
rate_limit.exceededHTTP 429You have exceeded the request rate limit for this key.
Fix: Test keys are limited to 500 req/min. Implement exponential backoff or upgrade to a live key.