API tokens
The public API authenticates with a bearer token. There are no API key/secret pairs and no session cookies.
Authorization: Bearer npapi.<tenant>.<random>The token carries its tenant in the middle segment. That is a routing and debugging convenience - it is not the security boundary. The random tail is the only secret part, and the tenant segment is verified against the stored record on every request.
How it is stored
Section titled “How it is stored”NextPKI stores a SHA-256 hash of the token, never the token itself. This has two consequences worth designing around:
- The value is shown once, at creation. Nobody - including us - can recover it later. Lost token means new token.
- A leaked token cannot be recognised by looking at the database. If you suspect exposure, revoke and reissue rather than trying to determine whether it was used.
Rotation
Section titled “Rotation”Create the new token, deploy it, then revoke the old one. Both work in parallel
until you revoke, so there is no cutover gap. Revocation is immediate - the next
request with the old token gets a 401.
Rotate on a schedule you can actually keep, and rotate immediately when someone with access leaves. A token has no expiry of its own.
Handling
Section titled “Handling”Treat tokens like passwords:
- Environment variables or a secret manager, never a repository.
- Never in a URL query string - those end up in access logs and proxy caches.
- One token per integration, so revoking one does not break the others.
- Least privilege: see scopes.
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
401 |
Missing, malformed, unknown or revoked token |
403 |
Valid token, but the scope does not cover this endpoint |
429 |
Rate limit exceeded - see rate limits |