Reference table
Authentication between systems
Sets out how each system proves its identity in each direction, and where the hospital's credentials for partners and providers are held.
For every exchange that crosses the hospital's edge or the platform's, Pensieve fixes how the side that opens it proves who it is and how the side it reaches is confirmed. This page sets out that proof in each direction, where the hospital's credentials for partners and providers are held, and how credentials are rotated and revoked.
Who proves what
The caller is the side that opens an exchange, and the receiver is the side it reaches. The table runs from orophin, the bridge, through each partner and provider service to staff sign-in. Its last column shows how each exchange is bound to the right receiver: a pinned certificate, a registered address, encryption only the receiver can open, or an assertion addressed to Pensieve alone.
| Exchange | Direction | How the caller proves its identity | How the receiver is verified |
|---|---|---|---|
| Bridge to platform | Outbound from the hospital network, then both ways on the link | Three proofs: a client certificate from Pensieve's integration certificate authority bound to the bridge's identity, a separate bridge token, and a signature over a fresh challenge | The bridge accepts only the platform certificate it pins |
| Platform to a partner FHIR server | Outbound from the platform | SMART Backend Services: an assertion signed with the hospital's key, exchanged at the partner's token endpoint for an access token | HTTPS to the address registered on the connection, and to the token endpoint the partner declares |
| Platform to the claims exchange | Outbound from the platform, with responses read back | The hospital's participant code, and a JWS signature on every bundle made with the hospital's own key | Every bundle is encrypted with JWE, so only the party it is addressed to can open it |
| Platform to ABDM | Outbound from the platform, with responses read back | The hospital's own ABDM client credentials | Health records are encrypted end to end with an elliptic-curve key agreement and AES-256-GCM, so only the requesting party can read them |
| Platform to an insurer or TPA | Outbound from the platform | A header key, a bearer token, basic credentials or mutual TLS, as set on the connection | HTTPS to the base address registered on the connection |
| Platform to a payment or messaging provider | Outbound from the platform | The credentials of the hospital's own merchant account or SMS, WhatsApp, email or voice provider account, read from the secret store | HTTPS to the provider's address |
| Payment gateway to platform | Inbound notification | An HMAC-SHA256 signature over the raw body, verified before the body is read | Delivered over HTTPS to the notification address registered with the gateway |
| Messaging provider to platform | Inbound receipt | The provider's signature on the receipt, verified before the receipt is read | Delivered over HTTPS to the receipt address registered with the provider |
| Identity provider to platform | Inbound sign-in, through the person's browser | A signed SAML assertion or OpenID Connect ID token, checked against the identity provider's keys configured for the organisation | The assertion names Pensieve as its audience and answers a sign-in Pensieve started; with OpenID Connect, Pensieve redeems the code with PKCE and its client secret |
A system on the hospital network that sends to the bridge is admitted by the network it sits on. How that leg is protected is set out in networks and trust zones.
Every row above is a registered bridge or connection, a provider adapter or a person's sign-in, which are the ways a system joins that connection methods sets out. Sessions on the interfaces people use are minted for people alone, and a member of staff works under the one identity described in identity and sign-in.
How the bridge proves itself
The bridge holds an identity bound to one site. Two operators bring that identity into service under separate permissions, and the bridge then proves it three ways each time it connects.
- 1
An operator registers the bridge
An operator with the registration permission registers the bridge in Westron for one site. Pensieve mints the bridge's identity and its bridge token and shows the token once. In the same step it records the bridge's intake grant, which lets the bridge deliver into this site.
- 2
A second operator enrols its certificate
The bridge generates its key pair on its own host, and its certificate request goes through enrolment under a separate permission. Pensieve's integration certificate authority signs a certificate bound to the bridge's identity, the platform pins it, and the private key stays on the host.
- 3
The bridge proves itself at each connection
Each time it connects, the bridge presents its client certificate, its bridge token and a signature over a fresh challenge from the platform. Any failed proof closes the connection silently, so a prober learns nothing.
- 4
The session renews
A session lasts at most sixty minutes, after which the bridge connects and proves itself again. Every frame on the link is attributed to the identity proved for its session, and the site is taken from the bridge's registration, never from a frame.
How the registration, enrolment and revocation permissions are held apart is set out in governance of integrated data.
Where credentials are held
Every credential that reaches a national, payer, provider or partner service belongs to the hospital and is held under the rules below.
The hospital, under its own registration, participation or account.
The platform's secret store, by reference, apart from the record store and every log.
One secret for each site and connection.
Pinned. A connection reads the exact version it names until a new one is pinned.
Read at the moment of the call, for that call alone.
Set for each connection or messaging channel, where the console shows the reference alone.
A second person approves before the claims or payment rail goes live.
Partner credentials stay off the bridge
Partner and provider credentials are resolved on the platform at the moment of each call and are never sent to the bridge, so the hospital's national, payer and provider accounts stay out of reach of anyone who takes the bridge host.
How a credential is entered against a connection is walked through in connections and credentials.
Rotation and revocation
A partner or provider credential is rotated by placing the new value in the secret store as a new version and pinning the connection to it. The next call reads the new version.
A bridge's certificate is renewed by a fresh enrolment, which issues a new certificate bound to the same identity and pins it. Revoking a bridge, under the third permission, withdraws its intake grant and closes its live sessions across the platform within seconds, and its next attempt to connect fails.
Common confusions
Is the bridge token an API key for other uses?
The bridge token is one of the proofs the bridge presents together with its certificate and a signed challenge, and it serves that bridge's link alone. It grants nothing on the interfaces people use.
Who holds the keys that sign our claims?
The hospital. The key that signs each claims bundle and the key that opens replies addressed to the hospital are its own, held by reference in the secret store and read at the moment of use. Each outgoing bundle is encrypted for the party it is addressed to.
Can two sites share one stored credential?
A secret is held for one site and one connection, so a service used at several sites keeps a separate secret at each, and each is rotated on its own.
Read how staff sign in through the hospital's identity provider in single sign-on, and how each leg between the zones is protected in networks and trust zones.