Authentication

The public Partner API uses bearer credentials issued to approved organisations. Keys must be stored and used server-side only.

API keys are registry-controlled credentials. They identify an approved sandbox, pilot, or private-beta capability; they are not public self-serve traffic switches and do not enable external GA access by themselves.

---

Key families

Key family	Prefix	Current use
Partner V2	ntp_partner_v2_<key-id>_*	Approved private-beta partner routes; V1 keys are rejected
Agent V2	ntp_agent_v2_<key-id>_*	Device-bound Edge Agent routes with sender proof on mutations

---

Request format

Send the key in the Authorization header for the public Partner OpenAPI routes:

POST /api/v1/estimate HTTP/1.1
Host: api.nowtoprint.com
Authorization: Bearer ntp_test_xxxxxxxxxxxxxxxxxxxx
Accept: application/json
Content-Type: application/json

Some private-beta control-plane endpoints still use explicit registry key headers. Webhook management (/api/v1/webhooks) requires:

POST /api/v1/webhooks HTTP/1.1
Host: api.nowtoprint.com
x-api-key: ntp_partner_v2_key_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

The key must be active and unexpired, and bind tenant, organization, principal, supplier, webhooks audience, and the fixed webhooks.manage scope. Format-only keys are rejected. This control-plane access does not mean quote, order, or event delivery automation is generally enabled for public production traffic.

---

Operational expectations

Topic	Guidance
Scope model	Key capabilities and limits depend on entitlement, registry state, and rollout posture
Rotation	Issue a new key in the V2 family, deliver its one-time secret through an approved channel, then revoke the predecessor
Idempotency	Use Idempotency-Key on metered reads or writes that may be retried; X-Idempotency-Key remains accepted for older clients. Keep values 160 characters or shorter; longer values are rejected, not truncated
Logging	Store request IDs and redact credentials from logs
Webhooks	Treat webhook secrets with the same care as API keys; event delivery remains pilot/rollout controlled

---

Common auth failures

Status	Meaning	Typical fix
401	Missing or invalid credential	Verify bearer header format and the correct key family
403	Scope or entitlement mismatch	Request the missing approved capability
429	Distributed quota exhausted	Wait until X-RateLimit-Reset
503	Credential or quota unavailable	Retry later; the service remains fail-closed

When an enabled V2 capability composes quota enforcement, quota is reserved in a Firestore transaction which writes a payload-free durable usage outbox event in the same transaction. Requests are not served when quota or audit storage is unavailable. Partner records may decode quota metadata, but that snapshot is not consumption authority. Disabled Partner v1 capabilities do not call the reservation port or emit quota 429; quota becomes a launch claim only after an enabled capability and deployed evidence prove the complete path.

---

Security checklist

• keep keys in server-side secret storage
• never ship keys into client-side JavaScript
• do not commit credentials or example live values to source control
• redact auth headers in logs, traces, and error payloads
• use separate sandbox, pilot, and approved-live credentials
• re-check /docs/api/openapi.yaml before assuming a route is public-current

---

Related docs