# auth.md

- Canonical: https://www.vitalsvault.com/auth.md
- Last updated: 2026-08-22

You are an agent. Vitals Vault does **not** support automated agentic registration (`register_uri`, `claim_uri`, or a self-serve `identity_assertion` ceremony). Read this walkthrough, then stop if you need a credential the Educational API does not require. Authentication uses the keyless Educational Biomarker API and an approval-gated partner FHIR R4 OAuth 2.0 PKCE S256 + PAR rail with manual registration.

Resource host: `https://www.vitalsvault.com`. Authorization host for the partner FHIR rail (when enabled): `https://www.vitalsvault.com`.

## Discover

There are two surfaces. Discover the right one before requesting a credential.

### Educational Biomarker API (public, keyless)

No credential is needed. Call `GET https://www.vitalsvault.com/api/v1/biomarkers` and related read routes over HTTPS. Rate limit: 100 requests per 15 minutes per client IP. Errors use RFC 9457 `application/problem+json` plus the legacy `{ success: false, error: { code, message } }` envelope.

There is no API key and no signup.

### Partner FHIR R4 API (approval-gated)

The partner resource is `https://www.vitalsvault.com/api/fhir/r4`. When the rail is enabled (`PARTNER_CLEAR_RAIL_ENABLED`), a 401 on FHIR R4 entry points carries:

```http
WWW-Authenticate: Bearer resource_metadata="https://www.vitalsvault.com/.well-known/oauth-protected-resource"
```

Fetch Protected Resource Metadata (RFC 9728) at that URL, or at the conventional path `https://www.vitalsvault.com/.well-known/oauth-protected-resource`. Fields: `resource`, `authorization_servers`, `scopes_supported` (patient/Patient.rs, patient/Observation.rs, patient/DiagnosticReport.rs), `bearer_methods_supported` (`header`), `resource_documentation`.

Authorization-server metadata (RFC 8414) is published at `https://www.vitalsvault.com/.well-known/oauth-authorization-server` **only where the rail is enabled**. Production currently keeps the rail dark, so those well-known documents return 404 until the flag is on. Do not treat a 404 as a registration endpoint.

There is no `agent_auth.register_uri` and no automated claim endpoint. The `agent_auth` profile from WorkOS is **not implemented**. Manual registration only.

## Pick a method

1. Educational content, ranges, or panel definitions → no auth. Use the Educational Biomarker API.
2. A consenting member's FHIR Patient / Observation / DiagnosticReport → OAuth 2.0 authorization code + PKCE S256 + PAR on the partner rail. Partner access is approval-gated through the partner application ([https://www.vitalsvault.com/partners](https://www.vitalsvault.com/partners)).
3. `identity_assertion`, anonymous agent registration, self-serve keys, or a public sandbox → **not available**. Do not invent a `register_uri`.

## Register

Partner access is approval-gated through the partner application ([https://www.vitalsvault.com/partners](https://www.vitalsvault.com/partners); form: [https://www.vitalsvault.com/partners/apply](https://www.vitalsvault.com/partners/apply)). There is no self-serve registration, no `register_uri`/`claim_uri` automation. Credentials are provisioned by Vitals Vault after approval.

1. A human applies at [https://www.vitalsvault.com/partners](https://www.vitalsvault.com/partners).
2. Email support@vitalsvault.com if you are an approved care partner integrating FHIR.
3. Vitals Vault provisions credentials after approval. Partners do not mint keys from this file.

Do not POST to `/agent/identity`. That path does not exist.

## Claim

There is no `claim_uri` and no device-code claim ceremony. Ownership of a partner application is established after approval, not by an agent polling for a `user_code`.

If you hold only an email address, you still cannot self-provision FHIR access.

## Use the credential

Educational API: send no `Authorization` header.

Partner FHIR (when the rail is enabled):

- PAR: `POST https://www.vitalsvault.com/api/oauth/par`
- Authorization: `https://www.vitalsvault.com/oauth/authorize` with PKCE `code_challenge_method=S256`
- Token: `POST https://www.vitalsvault.com/api/oauth/token` (`grant_type=authorization_code` + `code_verifier`, or `refresh_token`)
- Call `https://www.vitalsvault.com/api/fhir/r4` with `Authorization: Bearer <access_token>`
- Scopes: patient/Patient.rs, patient/Observation.rs, patient/DiagnosticReport.rs

Present the access token as a header bearer. There is no query-string bearer.

## Errors

| Situation | What you see | What to do |
| --- | --- | --- |
| Educational API unknown path | 404 `application/problem+json` with `success: false` | Use `/openapi.json` or `/developers` |
| Educational API rate limit | 429, `Retry-After`, `X-RateLimit-*` | Back off |
| Partner rail disabled | 404 on well-known metadata and OAuth routes | Do not retry registration; the rail is approval-gated |
| FHIR missing/invalid bearer | 401 `WWW-Authenticate: Bearer resource_metadata="…"` | Follow Discover; if you have no partner credentials, stop |
| `invalid_scope` | Token request rejected | Request only the three patient scopes above |
| `register_uri` / `identity_assertion` missing | There is no such endpoint | Manual registration; do not probe random `/agent/*` paths |

## Revocation

Partner tokens: `POST https://www.vitalsvault.com/api/oauth/revoke`. Educational API has no credential to revoke.

There is no RFC 8935 SET `events_endpoint` for agents. After approval is withdrawn, the next FHIR call returns 401/403.

## Agent safety

The Educational API must never receive PHI. FHIR access requires the consenting patient's authorization and least-privilege scopes (patient/Patient.rs, patient/Observation.rs, patient/DiagnosticReport.rs). Never log tokens. Agents cannot create accounts, accept magic links, submit identity data, or pay — those steps are for the person.