Authentication

The current RFQ create and organization-owned RFQ/quote read contract is generated at /api/v1/marketplace/openapi.json. The older /docs/api/openapi.yaml publication is a separate reference; do not assume the documents are identical. Confirm the environment origin and approved capabilities during onboarding.

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_partner_v2_<issued-key-id>_<secret>
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_<issued-key-id>_<secret>
Content-Type: application/json

The key must be active and unexpired, and bind organization, principal, allowed supplier identities, 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	RFQ deduplication is server-derived from its parsed body; other routes define their own retry identity
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	Organization capability denial	Request the missing approved capability
429	Distributed quota exhausted	Use the problem body’s resetAt
503	Credential or quota unavailable	Retry later; the service remains fail-closed

Every authenticated Partner v1 request consumes the Credential V2 fixed-window bucket (default 120/minute per credential/organization/scope), including requests that later reach a disabled estimate/order boundary. Bucket and payload-free usage outbox writes share a Firestore transaction; unavailable authority fails closed.

RFQ create additionally reserves its commercial daily allowance after catalog context and L2 resolution. That reservation replays an identical body without charging the daily counter again. This is distinct from the credential request bucket: retries still count as requests. Credential rejection, including wrong scope, uses 401; organization capability denial can use 403. Credential 429 provides resetAt in Problem Details; do not assume every Partner route supplies X-RateLimit or Retry-After headers.

Partner RFQ create currently derives its operation identity from the parsed request body. A caller-supplied Idempotency-Key does not choose that RFQ identity. Other surfaces have different rules: PDF partner attach supports an optional key, while metered data-product contracts are separate and remain external-dark.

Credential issuance is an authorized operator workflow with policy ids, organization and supplier bindings, commercial tier and at most 90 days lifetime. The secret is returned once and is excluded from stored idempotent replay; use approved secure delivery and revoke a replaced credential. The partner dashboard is not a working self-service key generator.

---

Source chain: consumeCredentialQuota writes its minute bucket and credential_v2_usage_outbox in one Firestore transaction; denial is PARTNER_API_RATE_LIMITED. The daily RFQ reservation port is called after catalog/L2 checks. Disabled Partner v1 estimate/order adapters do not reserve daily RFQ allowance, but authenticate and consume minute quota first.

Daily reservation denial returns 429 with PARTNER_RFQ_QUOTA_EXCEEDED; handle its quotaKind, limit, remaining and resetAt separately from minute-bucket denial.

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