SDKs & Client Libraries

Official Permissio SDKs are available now for Node.js and Python. Both are hand-written, fully typed wrappers over the Partner API with idiomatic clients, automatic Idempotency-Key generation, typed errors, and a webhook signature-verification helper.

Beta

The SDKs are published as 0.1.x betas. The API surface is stable, but minor changes may land before 1.0. Pin a version in production and watch the changelog for updates.

SDK status

Language	Package	Status
Node.js / TypeScript	permissio-sdk (npm)	✅ Available (beta)
Python	permissio (PyPI)	✅ Available (beta)
Other languages (Go, Ruby, …)	—	Generate from the OpenAPI spec (below)

---

Postman collection

Prefer Postman? Download the official collection and import it (File → Import):

⬇ permissio.postman_collection.json

Set the collection's apiKey variable to your sk_test_… (sandbox) or sk_live_… (live) key — every request inherits Bearer auth from the collection, so you can start calling endpoints immediately. baseUrl defaults to https://api.permissio.us. All 37 partner operations are included with example request bodies.

---

Node.js / TypeScript

npm install permissio-sdk
# or: pnpm add permissio-sdk  /  yarn add permissio-sdk

import { Permissio } from "permissio-sdk";

const client = new Permissio({
  apiKey: process.env.PERMISSIO_API_KEY!, // sk_live_… or sk_test_…
});

// Create an envelope from a template, then send it
const envelope = await client.envelopes.create({
  template_id: "tpl_…",
  title: "NDA — Acme Corp",
  signers: [
    { role_name: "Disclosing Party", email: "alice@example.com", name: "Alice Nguyen" },
    { role_name: "Receiving Party",  email: "bob@example.com",   name: "Bob Smith"   },
  ],
  variables: { effective_date: "2026-05-04", party_a_name: "Smartshares Limited" },
  expires_in_days: 14,
});

await client.envelopes.send(envelope.id); // dispatches signer invites

const detail = await client.envelopes.get(envelope.id);
console.log(detail.status); // "sent" → "in_progress" → "completed"

Use sk_test_… keys for sandbox mode — signer emails are suppressed and webhooks are tagged env: "sandbox".

Typed errors

Every API error is thrown as a PermissioApiError carrying the stable code, HTTP status, requestId, and details:

import { Permissio, PermissioApiError } from "permissio-sdk";

try {
  await client.envelopes.send("env_…");
} catch (err) {
  if (err instanceof PermissioApiError) {
    console.error(err.code);      // e.g. "invalid_state"
    console.error(err.status);    // e.g. 409
    console.error(err.requestId); // include in support tickets
  }
  throw err;
}

See the full list of code values in the errors reference.

---

Python

pip install permissio

Requires Python 3.9+ (uses httpx).

from permissio import Permissio

client = Permissio(api_key="sk_live_…")  # or sk_test_… for sandbox

envelope = client.envelopes.create(
    template_id="tpl_…",
    title="NDA — Acme Corp",
    signers=[
        {"role_name": "Disclosing Party", "email": "alice@example.com", "name": "Alice Nguyen"},
        {"role_name": "Receiving Party",  "email": "bob@example.com",   "name": "Bob Smith"},
    ],
    variables={"effective_date": "2026-05-04", "party_a_name": "Smartshares Limited"},
    expires_in_days=14,
)

client.envelopes.send(envelope["id"])       # dispatches signer invites
detail = client.envelopes.get(envelope["id"])
print(detail["status"])                      # "sent" → "in_progress" → "completed"

An async client is available too:

import asyncio
from permissio import AsyncPermissio

async def main():
    async with AsyncPermissio(api_key="sk_live_…") as client:
        env = await client.envelopes.create(template_id="tpl_…", signers=[...])
        await client.envelopes.send(env["id"])

asyncio.run(main())

---

Other languages

For any language without a first-party SDK, generate a fully typed client from the public OpenAPI spec — it needs no authentication and is served with CORS: *:

Format	URL
JSON	https://api.permissio.us/api/openapi/public.json
YAML	https://api.permissio.us/api/openapi/public.yaml

TypeScript (if you prefer a generated client over the SDK) — @hey-api/openapi-ts:

npx @hey-api/openapi-ts -i https://api.permissio.us/api/openapi/public.json -o ./src/permissio

Go — oapi-codegen:

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
oapi-codegen -generate types,client https://api.permissio.us/api/openapi/public.json > permissio.gen.go

Python (generated alternative) — openapi-python-client:

openapi-python-client generate --url https://api.permissio.us/api/openapi/public.json

---

Follow the changelog for SDK release announcements. Found a bug or want a language we don't cover yet? Let us know.