Overview
Parchment uses a multi-layered authentication approach for partners:
- Partner Registration - Partners are registered in our system with a unique Partner ID.
- Organization Registration - Each partner can have multiple organizations, each with their own credentials.
- Token Generation - Partners can generate JWT tokens for authenticated API requests.
- 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 1 hour
- Include specific scopes that determine permissions
- Are signed using RS256 algorithm
- Used as Bearer token in the Authorization header
- eg.
Authorization: Bearer <token>
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 1 hour
- 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.
