Quickstart

Base path /api/v1 on your deployment's origin. Everything is JSON, over HTTPS, and nothing in the API is cacheable.

The fastest way to see it work: sign up in the portal, verify your account, then create an API token from Account → API tokens with the generate scope. Every example below uses that token.

curl "https://your-host/api/v1/password?minPassLength=12&symbols=true" \
  -H "Authorization: Bearer $PNP_TOKEN"

{
  "passwords": ["orion-vega-draco47!"],
  "count": 1,
  "entropyBits": 41.9,
  "wordPoolSize": 6
}

That's an ad-hoc call - every parameter travels on the URL, same as the standard API. Once you know which settings you actually want, save them as an endpoint instead: you get a stable URL that takes no parameters at all, and can be changed from the portal without touching whatever calls it.

curl -H "Authorization: Bearer $PNP_TOKEN" \
  https://your-host/api/v1/e/8f2c4a10-3b7d-4e21-9f55-2a1c8e6b4d90

Authentication

Every call to the API is authenticated with a bearer token.

Authorization: Bearer pnp_A1B2C3D4E5F6G7H8_...

Get a token from the portal under Account → API tokens - see Tokens for scopes and limits. Scope it to exactly what your integration does; a token that only needs generate should only have generate.

Calling your own endpoint straight from a web page, rather than from a server, is off by default - see Browser access under Endpoints. Nothing else in the API answers a cross-origin request.

Errors

{ "error": { "code": "invalid_credentials", "message": "That email address and password do not match." } }

Two 403 codes are worth handling separately, because they mean something a client can act on rather than a mistake it made:

Generation

Scope generate. Requires a live subscription.

GET/e/{endpointId}

Runs a saved preset - the pattern to use once you know what you want.

curl -H "Authorization: Bearer $PNP_TOKEN" \
  https://your-host/api/v1/e/8f2c4a10-3b7d-4e21-9f55-2a1c8e6b4d90

{
  "passwords": ["orion-vega-draco47!"],
  "count": 1,
  "entropyBits": 41.9,
  "wordPoolSize": 6,
  "endpointId": "8f2c4a10-3b7d-4e21-9f55-2a1c8e6b4d90"
}

If the endpoint has allowOverrides, the query parameters below override the stored preset for that call. Otherwise they are ignored. An endpoint that is not yours returns 404, exactly as one that does not exist does. A request carrying an Origin header is additionally judged against the endpoint's browser allow-list.

GET/password

Ad-hoc generation, with the original API's query parameters - the same shape the standard API accepts.

Names are matched case-insensitively, as the standard API does. With every category switched off, animals is used. 666, 69 and 420 never appear in output unless useStandardBanList is turned off.

Batches are capped at 250 rather than the standard service's much larger limit: a Worker has a fixed CPU budget per request. Everything else behaves identically.

Endpoints

Saved presets. Up to 50 per account.

A preset is validated at save time by generating from it, so a combination that cannot produce a password is refused with an explanation rather than failing later in your own deployment.

config takes the query parameters from Generation above as JSON, in camelCase, plus:

Browser access

allowedOrigins on an endpoint is the list of origins permitted to call it from a browser. Empty - the default - means server-side use only.

{ "allowedOrigins": ["https://app.example.com", "http://localhost:3000"] }

Entries must be a scheme, host and optional port, and nothing else. https is required except for loopback. Wildcards and the opaque null origin are refused. Up to 10 per endpoint.

One thing worth being blunt about: a token in a page a browser downloaded is readable by anyone who visits that page. An allow-list means a stolen copy still will not work from a browser on an origin you did not nominate. It does nothing about curl. Treat it as defence in depth, not as protection for the token.

Word lists

Up to 25 lists, 5,000 words each, 64 KB per list.

A word is letters and digits only, 1–32 characters - anything that could change a password's structure is refused.

Ban lists

Words a password may never contain. Up to 25 lists, 250 entries each, 16 KB per list.

An entry is anything visible without spaces, up to 32 characters - unlike a word, because b@$$ has to be a legal thing to ban. Entries are capped tighter than words because every one of them is matched against every candidate password inside the generator's retry loop.

How an entry is matched

Write the plain word. bass also stops b4ss, b@ss, ba55, ba$$ and BASS. That matters more here than it might elsewhere, because the generator makes those substitutions itself: lettersForNumbers and lettersForSymbols turn bass into b@$$, and a literal filter would hand it straight back.

Two rules bound that:

• An entry with no letters is matched literally. 666 means the digits. Without this rule, 6 and 9 standing for g would make the standard entry 69 reject egg + grape.
• The password is never rewritten, only the entry is expanded. Folding both sides onto one letter looks equivalent and is not: with i and l folded together, banana + icecream reads as containing anal.

A word split by the separator still counts: with spacers on, pass + word is emitted as pass-word, and a ban on password catches it. These are substring bans, so a banned word inside an innocent one still matches - vacate contains cat.

Tokens

Created from the portal, signed in, with a fresh authenticator code. Not itself an API call your integration makes.

{
  "token": "pnp_A1B2C3D4E5F6G7H8_...",
  "scopes": ["generate"],
  "expiresAt": 1770000000,
  "warning": "Copy this now. It cannot be shown again."
}

Up to 25 live tokens. Maximum life one year; there is no non-expiring option.