Connection API Reference

Add AllClear to this app so it can read a user's records with their consent.Sections 1 to 8 and 9a are live in production today. Section 9b (the Consumer APIs on auser's access token) is not live yet: read it for context, but do not build against it.Partners reach the Consumer APIs today with Partner API credentials (see /partners).Do not invent endpoints, scopes or claims.IF THERE IS NO CODEBASE TO BUILD INTOIf the user has no codebase (they pasted this into a chat app), don't ask for a repo, zip orstack. Say in one plain sentence that connecting AllClear lets you read their own healthrecords with their permission, ask what they'd like to do with their records in everydaywords, and keep your replies non-technical.Check what you can do first. If you can add an MCP connection yourself, do. If you can't, givethe user these manual steps. In Claude: Settings → Connectors → Add custom connector, URLhttps://mcp.app.allclearid.com/mcp (note the /mcp), then Connect and approve in the AllClearapp; added this way, Claude shows as verified. In other apps: add AllClear as a custom MCPconnector with the URL https://mcp.app.allclearid.com/mcp in your app's connector or MCPsettings, then approve in the AllClear app. Hand-written OAuth (steps 1 to 8) is for agentsbuilding an app, not for chat users.LIVE IN PRODUCTION1. Register this app once as a public OAuth client (no secret):   POST https://oauth.app.allclearid.com/register   { "client_name": "<app name>",     "redirect_uris": ["<https redirect uri>"],     "token_endpoint_auth_method": "none",     "grant_types": ["authorization_code", "refresh_token"],     "response_types": ["code"] }   Keep the returned client_id. There is no secret, and no approval step or API key to   request: registration is open and immediate.2. To connect a user, send them to https://oauth.app.allclearid.com/authorize with   response_type=code, client_id, redirect_uri, scope="records:read offline_access",   code_challenge (S256), code_challenge_method=S256, state. On return, check state and iss   before using the code. To also sign the user in, add openid to scope and send a nonce   (see 9a).   Don't set resource yourself; MCP client libraries add it, and the server doesn't need it otherwise.3. Exchange the code: POST https://oauth.app.allclearid.com/token (form-encoded)   grant_type=authorization_code, code, redirect_uri, client_id, code_verifier.   Store access_token (1 hour) and refresh_token (30 days). Renew with   grant_type=refresh_token. Every refresh returns a new refresh_token and the old one stops   working, so store the new one each time and never refresh one connection in parallel:   presenting a used refresh_token revokes the connection. The 30 days is sliding: each   refresh issues a fresh 30-day refresh_token. Treat both tokens as opaque: only the   id_token is meant to be read, after verifying it against the JWKS (see 9a). Never log them.4. Read records over MCP: POST https://mcp.app.allclearid.com/mcp   Authorization: Bearer <access_token>   Accept: application/json, text/event-stream   Use a standard MCP client library if you can; it does the handshake for you. By hand: POST   initialize (protocolVersion 2025-06-18), then the notifications/initialized notification,   and send MCP-Protocol-Version: 2025-06-18 on every later request, plus Mcp-Session-Id if   the initialize response returned one. Then call tools/list, then tools/call with get_medications, get_conditions, get_allergies,   get_lab_results, get_vital_signs, get_immunizations, get_encounters, get_procedures,   get_care_plans, get_patient_insurance, list_patient_documents, search_medical_data.   Records come back as the source holds them: structured (fhir) plus document excerpts.   Health records are live today; further record types follow.5. On a 401, refresh the access token and retry once. If the refresh is refused too, drop   both tokens, clear anything cached, and send the user through authorize again. A refresh   token left unused for more than 30 days expires and the refresh returns invalid_grant:   that is an expiry, not the user disconnecting.6. Disconnect, from your side:   POST https://oauth.app.allclearid.com/revoke (form-encoded)   token=<refresh_token>&client_id=<client_id>   The user can also disconnect in the AllClear app, under Connections. Either way your   next MCP call returns 401 with a WWW-Authenticate: Bearer challenge.7. Discovery, if you need it:   https://oauth.app.allclearid.com/.well-known/oauth-authorization-server   https://oauth.app.allclearid.com/.well-known/openid-configuration   https://mcp.app.allclearid.com/.well-known/oauth-protected-resource   https://oauth.app.allclearid.com/.well-known/jwks.json8. The scopes you can ask for in step 2:   records:read     the permission to read the user's records. One permission, two                    surfaces: live over MCP today, and it gates the Consumer APIs on a                    user's token in section 9b when that ships.   offline_access   a standing connection: you receive a refresh token and access                    continues until the user disconnects or the refresh token goes 30                    days unused. Without it the share is one-time and ends when the                    access token expires. Live.   records:add      add records to the user's account.   messages:send    send the user a message.   account:assist   assisted actions on the user's behalf.                    The user can grant records:add, messages:send and account:assist on                    the consent screen today, but this brief does not cover calling them.                    Do not request them unless you need them; do not guess endpoints.   openid, profile, email, address, phone                    identity (OpenID Connect). Live: see section 9a.   These instructions cover the read path. Ask only for the scopes you actually use: the user   reviews what you asked for before approving, and can end the connection at any time.9a. Identity (OpenID Connect). Live in production. The discovery document is    https://oauth.app.allclearid.com/.well-known/openid-configuration. It advertises    userinfo_endpoint https://oauth.app.allclearid.com/userinfo, the scopes openid, profile,    email, address and phone, RS256 id_token signing and pairwise subjects. Add openid to the    same authorize call in step 2, and the token response carries an id_token (a JWT) alongside    the access token. Send a nonce on the authorize call whenever you request openid, and    check it matches in the id_token. Verify signature (RS256), iss =    https://oauth.app.allclearid.com, aud = your client_id, and exp, against the JWKS in    section 7.    The id_token carries registered claims only: iss, sub, aud, azp, auth_time,    at_hash, iat, exp, and nonce if you sent one. It carries no personal    data and no verification claim. sub is per client_id by default; when several clients are    linked to one organization it can be configured to be the same across them. Key users on    iss + sub.    Personal details come from GET /userinfo on the access token, released by scope:    profile (name, given_name, family_name, birthdate, gender), email (email),    phone (phone_number), address (address). Without a Bearer token /userinfo answers    401 with WWW-Authenticate: Bearer.NOT LIVE YET. DO NOT BUILD AGAINST THIS.9b. Consumer APIs on a user's OAuth token. Not live yet (coming). Today the Consumer APIs    are available to partners through a partner agreement, with Partner API credentials    issued by AllClear's integration team: partners use the Partner API documentation    (/partners). When calling them with a user's access token ships: a user's source    documents in their original form, fetched on the user's access token; and an event stream addressed    to your app. The event notification is thin and signed (an event id and type, with    your client_id as the audience, and no user in it by design). You fetch the event    itself with the client_credentials grant on your app's own credential, not a user    token, and the event names the patient it is about.