Skip to main content

​
Partner Token Creation

This guide explains how Parchment validates partner authentication tokens and how to implement proper token creation in your applications.

​
Token Structure

Parchment uses JWT (JSON Web Tokens) with the RS256 algorithm for partner authentication. JWT tokens consist of three parts:
  1. Header: Contains metadata about the token type and signing algorithm
  2. Payload: Contains claims about the entity (partner) and additional data
  3. Signature: Ensures the token hasn’t been altered

​
Token Payload

A typical token payload contains: 
{
  "organization_id": "ORG456",
  "partner_id": "PARTNER123",
  "user_id": "USER789",
  "scope": ["read:patients", "write:prescriptions"],
  "iat": 1682506249,
  "exp": 1682509849
}
FieldDescription
organization_idUnique identifier for the organization
partner_idUnique identifier for the partner
user_idIdentifier for the end-user (if applicable)
scopeArray of permission scopes granted to this token
iatIssued At - timestamp when the token was created
expExpiration - timestamp when the token expires

​
Validation Process

When validating a partner token, our API performs the following checks:
  1. Organization ID Check: Verifies the organization ID in the request path/params matches the one in the token
  2. Signature Verification: Validates the token signature using the appropriate public key
  3. Expiration Check: Ensures the token has not expired
  4. Scope Check: Confirms the token includes the required scope for the requested operation
  5. Organization Secret Check: Validates the provided organization secret matches our records

​
Required Headers

For successful authentication, API requests must include these headers: 
x-organization-secret: your_organization_secret
Authorization: Bearer eyJhbGciOiJSUzI1...

​
JWKS Endpoint

Parchment provides a JWKS (JSON Web Key Set) endpoint that serves the public keys needed to verify token signatures. This follows standard OAuth 2.0 practices for key rotation and management.

​
Error Responses

When token validation fails, you’ll receive an error response with HTTP status code 401 or 403 and a message explaining the reason:
StatusErrorDescription
401invalid_tokenThe token is malformed or has an invalid signature
401expired_tokenThe token has expired
403insufficient_scopeThe token does not have the required scope
403organization_mismatchOrganization ID in the request doesn’t match the token
401invalid_secretThe organization secret is invalid

​
Best Practices

  • Always verify tokens on the server-side, never in client-side code
  • Implement proper error handling for authentication failures
  • Use a token management library that handles JWT validation correctly
  • Don’t store tokens in local storage or cookies accessible by JavaScript
  • Implement token refresh logic to handle expiration gracefully