Bring Your Own Identity - Fasten Connect

There are additional fees involved with TEFCA IAS in live mode. Please contact support@fastenhealth.com or your Account Representative for more information

Overview

Bring Your Own Identity (BYOI) lets your application perform identity proofing with your own supported Credential Service Provider (CSP), then hand the verified identity to Fasten Connect. In the standard TEFCA IAS flow, Fasten sends the patient to a CSP such as CLEAR or ID.me and receives the verified ID Token directly. In BYOI mode, your application owns that CSP experience. Your backend sends the CSP-issued IAL2 ID Token to Fasten’s Identity service, receives a short-lived request_uri, and passes that value into Fasten Stitch so the patient can complete consent and provider selection.

BYOI is intended for organizations that have completed TEFCA subparticipant onboarding and have a CSP configured to issue ID Tokens with your organization’s HCID in the aud claim. If you do not have that setup yet, use the standard TEFCA IAS flow.

How It Works

BYOI separates identity proofing from record authorization:

Your application starts identity proofing - The patient begins in your product and verifies their identity with your CSP.
Your backend receives the CSP ID Token - The token represents the verified patient identity and must stay server-side.
Your backend creates a Pushed Authorization Request - You call Fasten’s Identity service with the CSP ID Token.
Fasten returns a request_uri - The value is single-use, short-lived, and tied to your Fasten client.
Your frontend launches Stitch - You pass the request_uri into the Fasten SDK.
Fasten collects patient consent - The patient reviews your application and authorizes access.
The patient selects providers - Fasten searches the TEFCA network and guides the patient through selecting the healthcare organizations they want to share.

Once the connection succeeds, continue with the normal Fasten data collection workflow using the emitted connection events and webhooks.

Supported CSPs

Fasten validates the CSP issuer selected in your Pushed Authorization Request. Supported idp values are:

CSP	`idp` value
CLEAR	`clear_csp`
ID.me	`idme_csp`
Persona	`persona_csp`

The CSP must issue an unexpired OpenID Connect ID Token that Fasten can verify. The token audience must include your organization’s pre-configured HCID.

Use test credentials with synthetic CSP users and live credentials with real patient identities. Test mode rejects non-synthetic email addresses.

Prerequisites

Before you build the BYOI flow, make sure you have:

Registered as a TEFCA subparticipant under Fasten with our QHIN.
An authorized CSP that can complete IAL2 identity proofing.
A CSP integration that can issue ID Tokens with aud set to your organization’s HCID.
Provided your organization’s HCID to Fasten.
TEFCA IAS enabled for the Fasten API mode you are using.
Generated a public_* ID and matching private_* key from the Fasten Developer Portal.

Keep your private_* key and CSP ID Token handling on your backend only.

Patient Experience

The patient experience follows the same broad shape as other identity verification flows, but your application controls the first identity-proofing step.

Step 1: Start in Your Application

Introduce the record-sharing flow in your product before sending the patient to your CSP. Patients should understand that they are verifying their identity so they can securely request their own health records through the TEFCA network.

Step 2: Verify Identity With Your CSP

The patient completes the CSP’s identity-proofing process. Depending on the provider, this may include account sign-in, government ID capture, selfie or biometric matching, phone verification, or another IAL2-compliant proofing step. Fasten does not receive the patient’s ID photos or proofing session artifacts. Fasten receives only the resulting CSP ID Token that your backend submits.

Step 3: Return to Your Application

After proofing succeeds, your backend requests and receives a Fasten request_uri. Your frontend then opens Fasten Stitch with that request_uri so the patient can continue without repeating identity verification. Fasten shows the patient a consent screen for your application. The patient can review the request before authorizing access to their records.

Step 5: Select Healthcare Providers

Fasten searches participating TEFCA healthcare organizations and prompts the patient to select the providers they want to share. After the connection completes, your application receives the usual Stitch events and Fasten webhooks.

Developer Flow

1. Complete Identity Proofing

Start the CSP identity-proofing flow from your application. When the CSP completes proofing, send the resulting ID Token to your backend.

Do not send the CSP ID Token directly from browser code to Fasten. Your backend must create the Pushed Authorization Request because it uses your Fasten private key. This also allows you to keep sensitive identity data out of the browser and gives you more control over error handling and retries.

2. Create A Pushed Authorization Request

Call POST https://identity.fastenhealth.com/oauth2/par from your backend. The request body must be application/x-www-form-urlencoded, and the request must use HTTP Basic auth with your Fasten public ID and private key.

curl -X POST https://identity.fastenhealth.com/oauth2/par \
  -u "public_test_xxxxxxxxxx:private_test_xxxxxxxxxx" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "scope=openid profile email" \
  --data-urlencode "response_type=code" \
  --data-urlencode "idp=clear_csp" \
  --data-urlencode "idp_id_token=eyJhbGciOiJSUzI1NiIs..."

Parameters

Parameter	Required	Description
`scope`	Yes	Must be `openid profile email`.
`response_type`	Yes	Must be `code`.
`idp`	Yes	The CSP that issued the ID Token. Supported values are `clear_csp`, `idme_csp`, and `persona_csp`.
`idp_id_token`	Yes	The CSP-issued ID Token for the verified patient.

Fasten validates that:

Your client credentials are valid.
Your organization has TEFCA and BYOI mode enabled.
The scope entries are allowed for your client.
The ID Token is unexpired.
The ID Token issuer matches the selected idp.
The ID Token aud matches your organization’s configured HCID.
The ID Token email is appropriate for the API mode.

Response

A successful request returns 201 Created.

{
  "request_uri": "urn:ietf:params:oauth:request_uri:4c7f0f56-9302-4217-98d3-3b4d1e5f98ad",
  "expires_in": 90
}

The request_uri is single-use and expires after 90 seconds.

3. Pass The `request_uri` To Fasten Stitch

Initialize Fasten Stitch with the request_uri returned by the PAR response.

<fasten-stitch-element
    public-id="public_test_xxxxxxxxxx"
    identity-request-uri="urn:ietf:params:oauth:request_uri:4c7f0f56-9302-4217-98d3-3b4d1e5f98ad">
</fasten-stitch-element>

Redeem the request_uri immediately after your backend creates it. If the patient takes too long or refreshes the page, create a new PAR request and relaunch Stitch with the new value.

4. Handle Completion Events

Listen for the same Fasten Stitch events you use in other consent flows. Store the resulting org_connection_id and related metadata so your backend can request exports and support the patient later.

Use widget.complete to update your frontend after Stitch finishes.
Use patient.connection_success as the durable backend signal.
Continue with POST /bridge/fhir/ehi-export when you are ready to retrieve records.

Security And Privacy

Keep your Fasten private key on your backend.
Submit the CSP ID Token only from your backend to Fasten’s Identity service.
Treat the CSP ID Token as sensitive patient identity data.
Do not store CSP proofing artifacts unless your own CSP agreement and privacy policies require it.
Fasten receives the verified ID Token, not the patient’s ID photos or CSP proofing session materials.
Log enough detail to support patients without logging raw ID Tokens.

Common Errors

Error	Cause
`invalid_client`	Missing, unknown, or invalid client credentials on the PAR request.
`unauthorized_client`	TEFCA or BYOI mode is not enabled for the credential’s API mode.
`invalid_target`	`audience` does not target an allowed Fasten Connect API audience.
`invalid_request`	Invalid form body, unsupported scope, redirect URI mismatch, ID Token issuer mismatch, HCID audience mismatch, or API mode email mismatch.
`invalid_request_uri`	The `request_uri` is invalid, expired, already consumed, or belongs to another client.
`invalid_grant`	Authorization code is invalid, expired, already used, not consented, or fails PKCE validation.

Implementation Checklist

Build and test the CSP identity-proofing redirect in your application.
Confirm the CSP ID Token issuer, signing keys, expiration, and aud claim with Fasten before going live.
Create the PAR request from your backend using the correct Fasten environment credentials.
Pass only the returned request_uri to the browser.
Launch Stitch before the request_uri expires.
Store org_connection_id from events or webhooks.
Use synthetic CSP identities in test mode.

For onboarding requirements, see TEFCA Subparticipant Registration. For Fasten-managed identity proofing, see the TEFCA IAS Developer Guide.

​Overview

​How It Works

​Supported CSPs

​Prerequisites

​Patient Experience

​Step 1: Start in Your Application

​Step 2: Verify Identity With Your CSP

​Step 3: Return to Your Application

​Step 4: Review Consent in Fasten

​Step 5: Select Healthcare Providers

​Developer Flow

​1. Complete Identity Proofing

​2. Create A Pushed Authorization Request

​Parameters

​Response

​3. Pass The request_uri To Fasten Stitch

​4. Handle Completion Events

​Security And Privacy

​Common Errors

​Implementation Checklist

Overview

How It Works

Supported CSPs

Prerequisites

Patient Experience

Step 1: Start in Your Application

Step 2: Verify Identity With Your CSP

Step 3: Return to Your Application

Step 4: Review Consent in Fasten

Step 5: Select Healthcare Providers

Developer Flow

1. Complete Identity Proofing

2. Create A Pushed Authorization Request

Parameters

Response

3. Pass The `request_uri` To Fasten Stitch

4. Handle Completion Events

Security And Privacy

Common Errors

Implementation Checklist