Authentication

PermitCore’s API uses bearer-token authentication. Every request must include an Authorization: Bearer <your-key> header.

Key format

API keys are opaque strings prefixed with pk_ (production) or pk_test_ (future test mode). Treat the entire string as secret.

pk_live_a1b2c3d4e5f6...   ← live key, never commit
pk_test_a1b2c3d4e5f6...   ← test key (future), never commit

Header convention

Authorization: Bearer pk_live_a1b2c3d4e5f6...
Accept: application/json

The Accept header is recommended but optional — responses default to JSON.

Where to get a key

Sign up at permitcore.io/signup
After magic-link sign-in, visit Account → API Keys
Your active key is shown once at creation — copy it then; we don’t store it in plain text after the initial display

Keys can be created either at signup (auto-issued first key) or programmatically via POST /v1/keys. Rotation is supported via DELETE /v1/keys/{prefix} followed by a fresh create.

Security best practices

Never commit keys to version control. Use environment variables.
Never embed keys in client-side JS. Server-to-server only.
Rotate keys quarterly or immediately if exposure is suspected.
Use one key per environment (production, staging, local). Easier to scope an incident if one is compromised.

Error responses for auth failures

Auth failures are RFC 9457 application/problem+json; branch on the type slug:

HTTP	`type` slug	When
`401`	`missing-credentials`	No `Authorization` header sent
`401`	`invalid-credentials`	Header sent but key is malformed / revoked / unknown
`403`	`insufficient-scope`	Key is valid but lacks scope for this endpoint

See Errors for the full response shape + retry guidance. See Data licensing for commercial-use terms once your key is active.

Example: handling auth in code

async function permitcore(path) {
  const res = await fetch(`https://api.permitcore.io${path}`, {
    headers: {
      Authorization: `Bearer ${process.env.PERMITCORE_API_KEY}`,
      Accept: "application/json",
    },
  });
  if (res.status === 401) throw new Error("Auth failed — check PERMITCORE_API_KEY");
  if (res.status === 403) throw new Error("Forbidden — key lacks scope for " + path);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

import os, httpx

def permitcore(path: str):
    r = httpx.get(
        f"https://api.permitcore.io{path}",
        headers={
            "Authorization": f"Bearer {os.environ['PERMITCORE_API_KEY']}",
            "Accept": "application/json",
        },
    )
    if r.status_code == 401:
        raise SystemExit("Auth failed — check PERMITCORE_API_KEY")
    if r.status_code == 403:
        raise SystemExit(f"Forbidden — key lacks scope for {path}")
    r.raise_for_status()
    return r.json()

Introduction

Concepts

API Reference

Reference

Key format

Header convention

Where to get a key

Security best practices

Error responses for auth failures

Example: handling auth in code

​Key format

​Header convention

​Where to get a key

​Security best practices

​Error responses for auth failures

​Example: handling auth in code

Key format

Header convention

Where to get a key

Security best practices

Error responses for auth failures

Example: handling auth in code