Skip to main content

​
Overview

Parchment uses a multi-layered authentication approach for partners:
  1. Partner Registration - Partners are registered in our system with a unique Partner ID.
  2. Organization Registration - Each partner can have multiple organizations, each with their own credentials.
  3. Token Generation - Partners can generate JWT tokens for authenticated API requests.
  4. Request Authentication - All API requests must include appropriate authentication headers.

​
Partner Registration

Partners must be registered in the Parchment system before they can access the API. This is typically done by the Parchment team. Once registered, partners receive:
  • A unique x-partner-id
  • A x-partner-secret for authentication

​
Organization Registration

Once a new organization is created, the partner will receive a x-organization-id and x-organization-secret for authentication. This secret is used to generate a JWT token for authenticated API requests.

​
Token Generation

Partners must generate a JWT token for authenticated API requests. Tokens have the following characteristics:
  • Valid for 6 hours — read expires_in in the token response for the exact lifetime
  • Include specific scopes that determine permissions
  • Are signed using RS256 algorithm
  • Used as Bearer token in the Authorization header
    • eg. Authorization: Bearer <token>
Cache your access token. Tokens are valid for 6 hours. Request one, hold it in memory, and reuse it for every call until it expires. Request a new token only on expiry or on a 401.Do not request a token per API call. That doubles your request volume, adds a round trip to every call, and is the most common integration mistake we see.

​
Security Considerations

Server-side only. Partner and organization credentials (x-partner-secret, x-organization-secret) and the bearer tokens derived from them are long-lived shared secrets. Never embed them in browser, mobile, or other client-side code, and never call the Parchment API directly from a frontend. CORS is not enabled, and any client-exposed credential can be read by end users (e.g. via DevTools) and used to impersonate your organization. Always proxy API calls through your backend.
  • Tokens have a limited lifetime of 6 hours
  • Use HTTPS for all API requests
  • Implement proper error handling for authentication failures

​
API Reference

For detailed API endpoints and request/response formats, see the API Reference.