Partner SSO Implementation Guide

This guide covers implementing server-to-server SSO authentication to allow your users to seamlessly access Parchment Portal without re-entering credentials.

Prerequisites

Valid partner credentials (partner_id, partner_secret, organization_id, organization_secret)
User must exist in Parchment, create either via Parchment portal or via /organizations/{organizationId}/users API

Setup

Signup to Parchment via Portal
Setup Organisation
Setup Partner integration using one of the Partner tiles
Copy the credentials into your system.

Note: If you are not using the create-user API you will need a way to manually capture the Parchment user_id of the user, in your system.

Implementation Steps

1. Initiate SSO Token

Make a server-to-server API call to generate an SSO token:

🚀 API Endpoint
POST /v1/sso

Headers:

x-partner-id: Your partner ID
x-partner-secret: Your partner secret
x-organization-id: Target organization ID
x-organization-secret: Organization secret
x-user-id: Parchment user ID to authenticate
Content-Type: application/json

Request Body:

If you want to go to patient profile

{
  "redirect_path": "/dashboard/patients/1234-5678-3456-2345"
}

If you want to directly prescribe

{
  "redirect_path": "/dashboard/patients/1234-5678-3456-2345/prescriptions"
}

For Embedded iFrame Integration - use /embed/ prefix

{
  "redirect_path": "/embed/patients/1234-5678-3456-2345/prescriptions"
}

Embedded iFrame Integration: If you want to embed Parchment Portal directly into your website using an iframe, use the /embed/ prefix in your redirect path. This optimizes the page for iframe display by removing navigation elements. See the Embedded iFrame Integration Guide for complete implementation details.

Response:

{
  "success": true,
  "data": {
    "sso_token": "eyJ...",
    "redirect_url": "https://portal.parchment.health/auth/sso?token=eyJ...&redirect=%2Fdashboard%2Fpatients%2F...",
    "expires_in": 300
  }
}

2. Open Parchment Portal

Create a button to open Parchment Portal in a new tab:

<button onclick="window.open(response.data.redirect_url, '_blank')">
  Prescribe
</button>

3. User Authentication

User is automatically authenticated in Parchment Portal
After successful authentication ,user is redirected to the specified redirect_path
Session is established for the user’s Parchment account

Important Security Notes

Token Expiry

SSO tokens expire in 5 minutes
Generate new tokens for each SSO attempt

Server-Side Only

🚨Never expose partner credentials to client-side code
SSO token generation must happen on your backend server
Only redirect URLs should be sent to the client

User Validation

Ensure the user_id corresponds to a valid user in your system
Verify user permissions before generating SSO tokens
Log all SSO attempts for audit purposes

Error Handling

Common Error Responses

400 Bad Request:

{
  "success": false,
  "error": {
    "type": "https://parchment.health/errors/invalid-request",
    "title": "Invalid request",
    "detail": "Missing required headers: x-user-id"
  }
}

401 Unauthorized:

{
  "success": false,
  "error": {
    "type": "https://parchment.health/errors/authentication-required",
    "title": "Unauthorized",
    "detail": "Invalid partner credentials"
  }
}

Error Handling Best Practices

Always validate API responses before redirecting users
Implement fallback authentication method if SSO fails
Display user-friendly error messages
Log errors for troubleshooting

Implementation Example

// Backend server endpoint
app.post('/sso-login-endpoint-in-your-backend', async (req, res) => {
  try {
    const { userId, redirectPath } = req.body;
    
    // Validate user permissions in your system
    if (!isUserAuthorized(userId)) {
      return res.status(403).json({ error: 'User not authorized' });
    }
    
    // Generate SSO token
    const response = await fetch('https://api.parchmenthealth.io/external/v1/sso', {
      method: 'POST',
      headers: {
        'x-partner-id': process.env.PARCHMENT_PARTNER_ID,
        'x-partner-secret': process.env.PARCHMENT_PARTNER_SECRET,
        'x-organization-id': process.env.PARCHMENT_ORG_ID,
        'x-organization-secret': process.env.PARCHMENT_ORG_SECRET,
        'x-user-id': userId,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        redirect_path: redirectPath || '/dashboard'
      })
    });
    
    const ssoData = await response.json();
    
    if (ssoData.success) {
      res.json({ redirect_url: ssoData.data.redirect_url });
    } else {
      res.status(response.status).json({ error: 'SSO token generation failed' });
    }
    
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

Support

For implementation assistance or troubleshooting:

Review API logs for detailed error messages
Contact Parchment support with specific error responses
Include request/response examples when reporting issues

SSO Integration

Partner SSO Implementation (recommended)

Partner SSO Implementation Guide

Prerequisites

Setup

Implementation Steps

1. Initiate SSO Token

2. Open Parchment Portal

3. User Authentication

Important Security Notes

Token Expiry

Server-Side Only

User Validation

Error Handling

Common Error Responses

Error Handling Best Practices

Implementation Example

Support

​Partner SSO Implementation Guide

​Prerequisites

​Setup

​Implementation Steps

​1. Initiate SSO Token

​2. Open Parchment Portal

​3. User Authentication

​Important Security Notes

​Token Expiry

​Server-Side Only

​User Validation

​Error Handling

​Common Error Responses

​Error Handling Best Practices

​Implementation Example

​Support

Partner SSO Implementation Guide

Prerequisites

Setup

Implementation Steps

1. Initiate SSO Token

2. Open Parchment Portal

3. User Authentication

Important Security Notes

Token Expiry

Server-Side Only

User Validation

Error Handling

Common Error Responses

Error Handling Best Practices

Implementation Example

Support