> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# TEFCA Individual Access Services (IAS) integration guide

> Configure your application to support TEFCA Individual Access Services with IDMe as the IAL2-verified credential service provider.

## Overview

The Trusted Exchange Framework and Common Agreement (TEFCA) is a U.S. healthcare interoperability framework that enables individuals to securely access their own health records across disparate networks. IDMe supports the TEFCA Individual Access Services (IAS) exchange purpose, empowering patients to request and receive their health information through apps of their choice using NIST 800-63-3 Identity Assurance Level 2 (IAL2) identity proofing.

**Intended audience** \
Developers and IAM administrators responsible for configuring federation between a TEFCA IAS application and IDMe.

**What you will build** \
A TEFCA-compliant patient access workflow where IDMe serves as the Credential Service Provider (CSP) issuing IAL2-verified identity tokens to your IAS application.

**Result** \
A patient logs into your app, verifies their identity via IDMe, and grants consent to retrieve their clinical records with a single IAS request across the TEFCA network.

## Authentication flow

The following steps outline the TEFCA IAS authentication flow between the patient, your application, the Qualified Health Information Network (QHIN), and IDMe:

The patient initiates a login to your application

Your application redirects the patient to IDMe for identity verification, including the TEFCA IAS policy scope

The patient completes authentication and NIST IAL2 identity proofing at IDMe

The patient reviews and grants consent to share their verified identity attributes with your application

IDMe issues a signed OIDC identity token containing verified demographic claims

Your application relays the IDMe identity token to the QHIN as part of the IAS query

The QHIN validates the token against IDMe's published JWKS endpoint and recognizes the patient's verified identity and consent

The QHIN securely transfers the patient's health records (USCDI v1 minimum) back to your application

## Prerequisites

Before beginning this integration, ensure you have the following:

* Communicate to your **IDMe Solution Consultant** that you intend to use the Individual Access token — an IAL2-level policy will be provisioned for your application
* A registered **OID (Object Identifier)** registered with HL7, required before a production client can be created
* A registered application capable of handling the **Authorization Code Grant** type
* A publicly accessible **redirect URI** (HTTPS required in production)
* Familiarity with [OIDC flows](/guides/oidc/overview), JWT validation, and token-based authentication concepts

## Environments

IDMe provides two environments:

#### Sandbox

`https://api.idmelabs.com/`

#### Production

`https://api.id.me/`

> **Note**
>
> All IDMe OIDC endpoints are derived from the base URL above. Replace the sandbox base URL with the production base URL in every endpoint you configure before going live.

### OIDC discovery endpoints

| Endpoint               | Sandbox                                                          | Production                                                |
| ---------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
| OIDC Issuer            | `https://api.idmelabs.com/oidc`                                  | `https://api.id.me/oidc`                                  |
| Discovery document     | `https://api.idmelabs.com/oidc/.well-known/openid-configuration` | `https://api.id.me/oidc/.well-known/openid-configuration` |
| Authorization endpoint | `https://api.idmelabs.com/oauth/authorize`                       | `https://api.id.me/oauth/authorize`                       |
| Token endpoint         | `https://api.idmelabs.com/oauth/token`                           | `https://api.id.me/oauth/token`                           |
| JWKS endpoint          | `https://api.idmelabs.com/oidc/jwks`                             | `https://api.id.me/oidc/jwks`                             |
| UserInfo endpoint      | `https://api.idmelabs.com/api/public/v3/attributes.json`         | `https://api.id.me/api/public/v3/attributes.json`         |

## Configure your application

### Register your application with IDMe

Before configuring your identity provider settings, you must register your application with IDMe to obtain OAuth 2.0 credentials.

Contact your **IDMe Solution Consultant** and communicate that you intend to use the Individual Access token. Provide the following details:

* **Application name**: The display name patients will see during the consent screen
* **OID**: Your HL7-registered Object Identifier (required for production)
* **Redirect URIs**: One or more HTTPS callback URLs your application will use after authentication (see [Redirect URIs](#redirect-uris) below)
* **Requested scopes**: At minimum `openid` plus the TEFCA IAS policy scope handle (provided by your Solution Consultant)
* **Environment**: Sandbox, production, or both

IDMe will provision an IAL2-level project and policy for your application, then return:

* `client_id`: Your application's unique identifier. This will either reflect your HL7 OID or an [IDMe](http://IDMe) specific client ID.
* `client_secret`: Your application's secret credential (store securely — never expose in client-side code)

Store your credentials securely in your application's secrets management system. You will use these in the token exchange step of the Authorization Code flow.

#### Redirect URIs

Redirect URIs must be pre-registered with IDMe. IDMe will reject any authorization request that specifies an unregistered `redirect_uri`.

Requirements:

* Must use HTTPS in production (HTTP is permitted in sandbox for `localhost` only)
* Must be an exact match — wildcard URIs are not supported
* Mobile apps may use custom URI schemes (e.g., `com.example.app://callback`) if registered

### Configure IDMe as an OpenID Connect identity provider

With your `client_id` and `client_secret` in hand, configure your application to initiate the Authorization Code flow against IDMe.

#### Authorization request

Direct the patient to IDMe's authorization endpoint with the following parameters:

**`Example`**

```bash Example
GET https://api.idmelabs.com/oauth/authorize
  ?response_type=code
  &client_id=IDME_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
  &scope=openid+YOUR_TEFCA_IAS_POLICY_SCOPE
  &state=RANDOM_STATE_VALUE
  &nonce=RANDOM_NONCE_VALUE
```

| Parameter       | Required    | Description                                                                             |
| --------------- | ----------- | --------------------------------------------------------------------------------------- |
| `response_type` | Yes         | Must be `code` for Authorization Code flow                                              |
| `client_id`     | Yes         | Your [**IDMe**](http://IDMe)**&#x20;specific** client ID, **not the HL7 OID**           |
| `redirect_uri`  | Yes         | Must match a pre-registered URI exactly; URL-encode the value                           |
| `scope`         | Yes         | Space-separated list including `openid` and your TEFCA IAS policy scope handle          |
| `state`         | Yes         | Random opaque value used to prevent CSRF attacks; validate on return                    |
| `nonce`         | Recommended | Unique per-session value embedded in the `id_token`; validate to prevent replay attacks |

Upon completion of the verification flow, IDMe redirects the patient back to your `redirect_uri` with an `authorization_code`. Parse this code from the URL and use it to perform the token exchange.

#### Token exchange

Exchange the authorization code for tokens using the token endpoint:

**`Example`**

```bash Example
curl --request POST \
  --url https://api.idmelabs.com/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://yourapp.example.com/callback' \
  --data-urlencode 'client_id=urn:oid:1.2.3.4.5.6' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET'
```

| Parameter       | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `grant_type`    | Must be `authorization_code`                                                  |
| `code`          | The authorization code returned to your redirect URI                          |
| `redirect_uri`  | Must exactly match the URI used in the authorization request                  |
| `client_id`     | Your [**IDMe**](http://IDMe)**&#x20;specific** client ID, **not the HL7 OID** |
| `client_secret` | Your application secret                                                       |

#### Verification result types

The token response varies depending on whether identity verification was successful.

**Successful verification** — IDMe returns an `access_token`, `id_token`, and `refresh_token`. The `id_token` is only issued when the patient's demographics have been fully validated to IAL2. Use the `id_token` to relay the patient's identity to the QHIN.

**`Example`**

```json Example
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 300,
  "id_token": "eyJ...",
  "refresh_token": "eyJ..."
}
```

#### OIDC identity token (id_token)

IDMe issues an `id_token` signed using RS256. The token payload follows standard OIDC claim names and includes TEFCA-required demographic attributes. The `aud` claim reflects your OID-formatted `client_id`.

**`Example`**

```json Example
{
  "iss": "https://api.idmelabs.com/oidc",
  "sub": "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789",
  "aud": ["urn:oid:1.2.3.4.5.6"],
  "iat": 1700000000,
  "exp": 1700003600,
  "auth_time": 1700000000,
  "nonce": "RANDOM_NONCE_VALUE",
  "jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "given_name": "JANE",
  "middle_name": "MARIE",
  "family_name": "DOE",
  "birthdate": "1985-04-12",
  "gender": "F",
  "email": "jane.doe@example.com",
  "phone_number": "+15551234567",
  "address": {
    "country": "US",
    "formatted": "123 MAIN ST, APT 4B, SPRINGFIELD, IL 62701 US",
    "locality": "SPRINGFIELD",
    "postal_code": "62701",
    "region": "IL",
    "street_address": "123 MAIN ST, APT 4B"
  },
  "historical_address": [
    {
      "formatted": "456 OAK AVE, CHICAGO, IL 60601",
      "locality": "CHICAGO",
      "postal_code": "60601",
      "region": "IL",
      "street_address": "456 OAK AVE"
    }
  ]
}
```

> **Note**
>
> The exact claim names returned depend on your IDMe policy configuration. Work with your IDMe Solution Consultant to confirm which attributes your policy handle returns and how they map to the TEFCA required demographics.

####

#### Required TEFCA IAS demographics

Per the Sequoia Project IAS SOP, the following patient demographics **must** be validated to IAL2 and present in the token:

| Attribute        | OIDC Claim    | Notes                                                                                                                                                                                                                                          |
| ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Legal first name | `given_name`  |                                                                                                                                                                                                                                                |
| Legal last name  | `family_name` |                                                                                                                                                                                                                                                |
| Date of birth    | `birthdate`   | YYYY-MM-DD format                                                                                                                                                                                                                              |
| Address          | `address`     | A single object formatted as: `“address”:{` `“formatted”:”1060 West Addison Street, Chicago, IL 60613 USA”, “street_address”:”1060 West Addison Street”, “locality”:”Chicago”, “region”:”Illinois”, “postal_code”:”60613”, “country”:”USA” },` |
| Nickname         | `nickname`    | [IDMe](http://IDMe) does not currently support nickname and will return `Unknown` per IAS spec.                                                                                                                                                |

#### TEFCA IAS demographics that must be included if known

Per the Sequoia Project IAS SOP, the following patient demographics **must** be validated to IAL2 and present in the token if they are known:

| Attribute          | OIDC Claim             | Notes                                                                                                                                                                                                                                                           |
| ------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Historical address | `historical_address`   | An object or array of objects formatted as: `“historical_address”:{ “formatted”:”31 Spooner Street, Quahog, Rhode Island 02907”, “street_address”:”31 Spooner Street”, “locality”:”Quahog”, “region”:”Rhode Island”, “postal_code”:”02907”, “country”:”USA” },` |
| Middle Name        | `middle_name`          |                                                                                                                                                                                                                                                                 |
| Nickname           | `nickname`             | [IDMe](http://IDMe) does not currently support nickname and will return `Unknown` per IAS spec.                                                                                                                                                                 |
| Email              | `email`                |                                                                                                                                                                                                                                                                 |
| Phone              | `phone_number`         |                                                                                                                                                                                                                                                                 |
| SSN                | `SSN`                  |                                                                                                                                                                                                                                                                 |
| Last 4 of SSN      | `SSN_Last_four_digits` |                                                                                                                                                                                                                                                                 |
| Gender             | `gender`               |                                                                                                                                                                                                                                                                 |

### Validate the token

Before relaying the identity token to a QHIN, validate it against IDMe's public key. Fetch the JWKS from the endpoint below and use a standard JWT library to verify the token signature using the key matching the token's `kid` header value.

**`Example`**

```bash Example
GET https://api.idmelabs.com/oidc/jwks
```

When validating, confirm all of the following:

* The token **signature** verifies against the JWKS public key
* The `iss` claim matches IDMe's issuer URI for the environment (sandbox or production)
* The `aud` claim matches your registered `client_id`
* The `exp` claim has not elapsed (token has not expired)
* The `iat` claim is in the past
* The `nonce` claim matches the value sent in your authorization request

> **Warning**
>
> Never relay an identity token to a QHIN without first completing full token validation. An invalid or expired token will be rejected by the QHIN and may expose your integration to replay attacks.

## Test the integration

Use the IDMe **sandbox environment** (`https://api.idmelabs.com/`) to validate your integration end-to-end before promoting to production.

#### Initiate an authorization request

Do this from your application using your sandbox `client_id` (OID format) and your TEFCA IAS policy scope. Confirm the redirect correctly lands on the IDMe sandbox login page.

#### Complete identity verification

Use the IDMe sandbox test credentials provided by your Solution Consultant. The sandbox simulates the full IAL2 proofing flow without requiring real identity documents.

#### Inspect the token response

Confirm that `id_token` and `refresh_token` are present, indicating a successful verification. Decode the `id_token` (e.g., at [jwt.io](https://jwt.io)) and verify:

* `iss` matches `https://api.idmelabs.com/oidc`
* `aud` matches your OID-formatted `client_id`
* All required TEFCA demographics are present (name, DOB, address claims)
* The `nonce` matches the value sent in the authorization request

#### Validate the token signature

Fetch the JWKS from `https://api.idmelabs.com/oidc/jwks` and confirming the signature verifies against the key matching the token's `kid` header value.

#### Submit a test IAS query

Send this to your QHIN's sandbox or test environment with the token relayed in the appropriate format (SAML attribute or `tefca_ias` FHIR extension). Confirm the QHIN accepts the token and returns a successful query response.

#### Test a failed verification

Confirm your application handles an unsuccessful response (no `id_token` in the token response) gracefully, without attempting to relay a non-existent token to the QHIN.

#### Test edge cases

Test multiple cases including expired tokens, mismatched `nonce` values, and `historical_address` arrays with multiple entries, to confirm your parsing and error handling behaves as expected.

> **Note**
>
> Token expiry defaults to 5 minutes (`expires_in: 300`). Request a fresh token for each IAS query rather than caching tokens across sessions.

## Security best practices

When extracting claims from the identity token, follow these best practices to maintain a secure and reliable integration:

**Validate the token** — Always validate the token before extracting claims. Verify the signature, and confirm the `exp` and `iat` claims ensure the token is still valid. Never relay an unvalidated token.

**Check the audience (`aud`)** — Confirm the `aud` claim matches your `client_id`. This ensures the token was issued for your application and not for a different relying party.

**Verify the issuer (`iss`)** — Ensure `iss` matches IDMe's issuer URI for the active environment. Tokens from the sandbox issuer must never be accepted in production and vice versa.

**Handle claims securely** — Extract only the claims your application needs to minimize data exposure. Treat demographic attributes (email, phone, address) as sensitive data and ensure compliance with applicable privacy regulations.

**Use the `state` parameter** — Always generate a unique `state` value per session in your authorization request and validate it on return. This prevents cross-site request forgery (CSRF) attacks.

**Use the `nonce` parameter** — Embed a unique `nonce` in the authorization request and validate it in the returned `id_token`. This prevents token replay attacks.

**Do not cache JWKS keys indefinitely** — Rotate your cached public keys periodically by re-fetching the JWKS endpoint. IDMe may rotate signing keys, and stale cached keys will cause signature validation failures.

**Log and monitor** — Log token validation attempts and monitor for unusual patterns, such as repeated validation failures or tokens with unexpected `aud` or `iss` values, which may indicate an attack.

## Troubleshooting

### Token validation failures

If the QHIN rejects the identity token, check the following:

| Symptom                               | Likely cause                                  | Resolution                                                                             |
| ------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------- |
| Signature verification failed         | Stale cached JWKS keys                        | Re-fetch JWKS from IDMe's endpoint; do not cache keys indefinitely                     |
| `iss` mismatch                        | Environment mismatch (sandbox vs. production) | Ensure token issuer and QHIN environment match                                         |
| `aud` mismatch                        | Token issued for a different client           | Confirm your OID-formatted `client_id` matches what is registered with IDMe            |
| `id_token` absent from token response | Verification was unsuccessful                 | Check verification session endpoint for failure reason; do not proceed with QHIN query |

### Consent screen not appearing

If patients are not presented with a consent screen to share identity attributes, confirm that your authorization request includes the correct TEFCA IAS policy scope handle. The scope drives which attributes are requested and triggers the consent screen. Contact your IDMe Solution Consultant to verify your policy scope configuration.

## Reference

* [Sequoia Project IAS Implementation SOP v2.0](https://rce.sequoiaproject.org/wp-content/uploads/2024/08/XP-Implementation-SOP-IAS.pdf)
* [IAS Provider Requirements SOP v2.1](https://rce.sequoiaproject.org/wp-content/uploads/2026/01/SOP-IAS-Provider-Requirements_v2.1_508.pdf)
* [Facilitated FHIR Implementation SOP](https://rce.sequoiaproject.org/wp-content/uploads/2024/07/SOP-Facilitated-FHIR-Implementation_508-1.pdf)
* [TEFCA Guide – September 2024](https://rce.sequoiaproject.org/wp-content/uploads/2024/10/TEFCA-Guide-September-2024_508.pdf)
* [HL7 OID Registry](https://www.hl7.org/oid/)
* [IDMe OIDC Overview](/guides/oidc/overview)