Postalform Com Authentication

generated: '2026-09-19'
method: searched
source: https://postalform.com/developers
derived_from:
- openapi/postalform-com-projects-openapi.json
- openapi/postalform-com-machine-payments-openapi.json
docs:
- https://postalform.com/developer-mail-api
- https://postalform.com/agents
- https://postalform.com/.well-known/mcp.json
summary:
  types: [http, none, payment-gated]
  api_key_in: [header]
  oauth2_flows: []
  note: >-
    Only ONE of PostalForm's three surfaces uses a credential. The Projects API declares a single http bearer
    scheme (bearerAuth) applied per operation to all 25 operations; the bearer is a workspace API key with a
    documented prefix — pf_test_ for the free simulated environment, pf_live_ for real mail on prepaid
    credits — rotated by POST /api/v1/api-keys/rotate {mode}, which returns the secret once. The Machine
    Payments API declares NO securitySchemes and an empty top-level security[]; every paid operation is
    gated by an HTTP 402 payment challenge (x402 PAYMENT-REQUIRED / MPP WWW-Authenticate: Payment) rather
    than by identity, and the free reads and validates need nothing. The MCP server requires no credential
    to connect, initialize or list tools ("No API key is required for the hosted MCP endpoint today";
    "contact support@postalform.com for allowlisting"), and its money-moving tools are gated by hosted
    checkout, a buyer-approved Stripe shared payment token or the same 402 challenges. No OAuth 2.0 or OIDC
    exists on any host (/.well-known/oauth-authorization-server, oauth-protected-resource and
    openid-configuration all 404 on postalform.com and projects.postalform.com).
schemes:
- name: bearerAuth
  type: http
  scheme: bearer
  surface: PostalForm Projects Public API (https://projects.postalform.com/api/v1)
  applied_to: 'all 25 operations (per-operation security [{bearerAuth: []}]; no global security block)'
  credential: workspace API key
  key_prefixes: {test: pf_test_, live: pf_live_}
  header_example: 'Authorization: Bearer pf_test_...'
  issuance: 'https://projects.postalform.com/signup (dashboard) or Stripe Projects provisioning of postalform/mail, which returns POSTALFORM_TEST_API_KEY and POSTALFORM_LIVE_API_KEY'
  rotation: 'POST /api/v1/api-keys/rotate {mode: test|live} -> ApiKeyRotation {api_key (returned once), api_key_prefix}; GET /api/v1/api-keys lists prefixes and status active|disabled|revoked with last_used_at'
  scopes: none (one key per mode; no scoped permissions documented)
  sources: [openapi/postalform-com-projects-openapi.json, https://postalform.com/developer-mail-api]
- name: none (payment-gated)
  type: none
  surface: PostalForm Machine Payments API (https://postalform.com/api/machine/*)
  applied_to: all 17 operations
  gate: >-
    HTTP 402. x402 family: PAYMENT-REQUIRED challenge, PAYMENT-SIGNATURE on retry, PAYMENT-RESPONSE on
    success (USDC on Base). MPP family: one WWW-Authenticate: Payment challenge per method (tempo, stripe,
    card), Authorization: Payment on retry, Payment-Receipt on success. Reads (forms catalog, schemas, order
    status) and validate endpoints are open.
  note: 'The OpenAPI declares "security": [] at the top level and no components.securitySchemes — an accurate declaration of "no authentication", not an omission.'
  sources: [openapi/postalform-com-machine-payments-openapi.json, https://postalform.com/agents]
- name: none (MCP)
  type: none
  surface: MCP server (https://postalform.com/mcp) and its UCP (/ucp/mcp) and ACP (/acp/mcp) siblings
  applied_to: initialize, tools/list, resources/list, read-only tools
  gate_on_writes: 'hosted checkout_url (human pays on Stripe-hosted page); complete_checkout with a Stripe shared payment token (spt_..., provider stripe); postalform.create_machine_order 402 challenge retried with payment_authorization (MPP) or payment_signature (x402). UCP calls additionally require a platform profile in _meta.ucp.profile.'
  rfc9728: 'not served — /.well-known/oauth-protected-resource 404 on the MCP host'
  sources: [https://postalform.com/.well-known/mcp.json, https://postalform.com/developers, https://postalform.com/.well-known/capability-card.json]
webhook_verification:
  header: PostalForm-Signature
  secret: endpoint-scoped signing_secret, returned once on create/rotate
  source: https://postalform.com/developer-mail-api ("Verify the PostalForm-Signature header before trusting webhook payloads")
  note: The signature algorithm and header format are not documented publicly.