Authentication

The Paqet Public API authenticates every request with an API key — there's no OAuth flow, no session, no cookies.

How API keys work

A key looks like pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. The pk_live_ prefix is stored and shown in the Developer Portal so you can identify a key without ever seeing its secret again — only a cryptographic hash of the secret is stored server-side, the same way passwords are. The plaintext key is shown exactly once, at creation time.

The Authorization header

Send the key as a Bearer token on every request:

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid header receive 401 Unauthorized with code API_KEY_INVALID.

Security recommendations

  • Never commit keys to source control. Use environment variables or a secrets manager.
  • Never expose keys in frontend code. A key embedded in browser JavaScript, a mobile app, or any client shipped to end users can be extracted and abused. Call the Paqet API from your own backend instead.
  • Scope keys narrowly. A key only needs the scopes for the endpoints it actually calls — see Scopes.
  • Set an expiration unless a key genuinely needs to live forever.

Rotation

To rotate a key: create a new one with the same scopes, switch your integration over, then revoke the old key. There's no "regenerate secret" for an existing key — a new secret always means a new key, so old and new can run side by side during a safe rollout.

Expiration

Keys can be created with a fixed lifetime (30 days, 90 days, 1 year) or set to never expire. An expired key fails with 401 API_KEY_EXPIRED — create a replacement before the old one lapses if you don't want downtime.

Revocation

Revoking a key from the Developer Portal takes effect immediately and is permanent — a revoked key can never be reactivated. Requests using a revoked key fail with 401 API_KEY_REVOKED.