Authentication

OnePath Connect uses two complementary authentication mechanisms: a partner API key for your server-to-server calls, and a user consent JWT for each individual user interaction.

Partner API Key

Your API key identifies your organization. It must be kept secret — never expose it in client-side code.

X-API-Key: onepath_production_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys look like onepath_sandbox_.... Production keys look like onepath_production_.... All requests to /partner/v1/ require this header.

User Consent Token

Every user interaction also requires a short-lived JWT that proves the user has consented to this specific data access. Your server generates this token using your private key.

// Node.js example
import { SignJWT } from "jose";

const consentToken = await new SignJWT({
  sub: "your-internal-user-id",
  partner: "your-partner-id",
  scope: "full-health",
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
})
  .setProtectedHeader({ alg: "RS256" })
  .sign(yourPrivateKey);

Pass it as a second header:

X-Consent-Assertion: <consent-jwt>

Acting on a member's behalf (acting_party)

If a clinician or staff member is acting on a member's behalf — for example, a provider-facing application where a treating clinician reviews and updates a member's record — you can optionally name them on the same consent token so they appear in OnePath's own audit trail, not only in yours:

{
  "sub": "your-internal-user-id",
  "partner": "your-partner-id",
  "scope": "full-health",
  "iat": 1756600000,
  "exp": 1756603600,
  "acting_party": { "id": "your-internal-clinician-id", "role": "clinician" }
}

acting_party is optional and additive. Omit it entirely for member self-service calls — the default, and unchanged from today. id is whatever identifier you already use internally for the acting user; OnePath does not resolve or validate it against anything, and stores it for audit/reconciliation only, the same trust model as sub. role is currently a small closed set (clinician), with staff and system reserved for future use.

Adding acting_party does not change any response shape and does not require a new scope — it's purely additive to the consent token you already send.

Sandbox Credentials

In the sandbox environment, we provide pre-signed consent tokens so you can test immediately without managing keys.

See Sandbox Environment for test credentials.