| Field | Value |
|---|---|
authorization_endpoint | <base>/auth/authorize |
token_endpoint | <base>/auth/token |
introspection_endpoint | <base>/auth/introspect |
jwks_uri | <base>/.well-known/jwks.json |
grant_types_supported | authorization_code, client_credentials, password, implicit, urn:ietf:params:oauth:grant-type:token-exchange |
token_endpoint_auth_methods_supported | client_secret_basic, client_secret_post, private_key_jwt |
token_endpoint_auth_signing_alg_values_supported | RS384, ES384 |
code_challenge_methods_supported | S256 |
capabilities | launch-standalone, launch-ehr, client-public, client-confidential-symmetric, client-confidential-asymmetric, permission-patient, permission-user, permission-v1, permission-v2, permission-offline, sso-openid-connect |
scopes_supported | openid, profile, email, launch, launch/patient, patient/*.cruds, system/*.cruds, user/*.cruds, fhirUser, offline_access, online_access |
| Parameter | Description |
|---|---|
response_type | Fixed value code. |
client_id | Client resource id. |
redirect_uri | Must match the registered Client.auth.authorization_code.redirect_uri. |
scope | Space-separated SMART scopes. Include launch/patient for standalone or launch for EHR launch, plus openid fhirUser for identity and offline_access to receive a refresh token. |
aud | FHIR base URL the app intends to call (typically <base>/fhir). |
state | Opaque value used to prevent CSRF; the server echoes it on the redirect back. |
code_challenge + code_challenge_method | Required for public apps (PKCE). code_challenge_method is always S256. |
launch | EHR launch only — the JWT identifier the EHR passed to the app. |
&redirect_uri=https://app.example.com/redirect
&client_id=my-public-smart-app
&code_verifier=
```
Confidential clients omit `client_id` from the body and authenticate with `Authorization: Basic ` (or send `client_id` + `client_secret` in the body).
{% endtab %}
{% tab title="Response" %}
```json
{
"token_type": "Bearer",
"access_token": "",
"refresh_token": "",
"id_token": "",
"scope": "launch/patient openid fhirUser offline_access patient/*.read",
"patient": "",
"expires_in": 3600,
"need_patient_banner": true
}
```
{% endtab %}
{% endtabs %}
### Refresh token
If the app requested `offline_access` it can refresh the access token without user interaction:
```http
POST /auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=
&client_id=my-public-smart-app
```
## SMART Backend Services (system-to-system)
Used by Provider Access, Payer-to-Payer, and PAS. The client signs a JWT with its private key; Payerbox verifies it against the client's JWKS endpoint registered at onboarding. No client secret is shared.
### Client registration
Each backend partner is registered as an Aidbox `Client` resource with `grant_types: ["client_credentials"]`, `auth.client_credentials.client_assertion_types: ["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"]`, and a `jwks_uri` (or inline `jwks`) carrying the partner's public keys:
```json
PUT /Client/partner-payer
Content-Type: application/json
{
"resourceType": "Client",
"id": "partner-payer",
"active": true,
"grant_types": ["client_credentials"],
"auth": {
"client_credentials": {
"client_assertion_types": ["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"],
"token_format": "jwt",
"access_token_expiration": 300
}
},
"jwks_uri": "https://partner.example.com/.well-known/jwks.json",
"scope": ["system/*.read"]
}
```
### HL7 B2B authorization extension (UDAP)
Member-match and Payer-to-Payer operations identify the calling organization from the [UDAP HL7 B2B Authorization Extension](https://hl7.org/fhir/us/udap-security/b2b.html#b2b-authorization-extension-object), not from any `Client` field. Aidbox produces the `hl7-b2b` extension on issued access tokens automatically; no extra configuration is required. Payerbox reads it from the token JWT under `extensions.hl7-b2b`:
```json
{
"sub": "partner-payer",
"extensions": {
"hl7-b2b": {
"version": "1",
"organization_id": "http://hl7.org/fhir/sid/us-npi#1234567893",
"purpose_of_use": ["..."]
}
}
}
```
`organization_id` is a single string in `#` form, split on the last `#`. Any identifier system works: NPI, NAIC, or CARIN BB `payerid`. Operations that read it:
| Operation | Uses `organization_id` for |
|---|---|
| [`$bulk-member-match`](operations/bulk-member-match.md) | Requesting-payer identity; stamped onto `MatchedMembers`; matched against Consent `provision.actor[role=IRCP]` |
| [`$provider-member-match`](operations/provider-member-match.md) | Caller identity |
| [`$davinci-data-export`](operations/davinci-data-export.md) (`payertopayer`) | Gates the opt-in export and resolves the requesting payer |
A non-admin caller without the claim gets `403`.
### Client assertion JWT
The client signs a short-lived JWT with its private key. Payerbox verifies the signature against the client's JWKS.
**Header**
| Field | Value |
|---|---|
| `alg` | `RS384` or `ES384` |
| `kid` | Key id matching one entry in the client's JWKS |
| `typ` | `JWT` |
| `jku` (optional) | TLS-protected URL of the client's JWK Set — must match `Client.jwks_uri` when present |
**Claims**
| Claim | Value |
|---|---|
| `iss` | Client id |
| `sub` | Client id (same as `iss`) |
| `aud` | Token endpoint URL — `
```
{% endtab %}
{% tab title="Response" %}
```json
{
"token_type": "Bearer",
"access_token": "",
"scope": "system/Patient.read system/ExplanationOfBenefit.read",
"expires_in": 300
}
```
{% endtab %}
{% endtabs %}
### Client JWKS
At onboarding, the partner registers either a `jwks_uri` (preferred — Payerbox refreshes the cached keys per the `Cache-Control` header) or an inline `jwks` array. Each JWK must include `kty` and `kid`; RSA keys also need `n` and `e`, EC keys need `crv`, `x`, and `y`. Key rotation is non-breaking — publish the new key, keep the old one until clients have rotated, then retire the old key.
## Client Credentials
Plain OAuth 2.0 `client_credentials` grant with a pre-shared `client_id` + `client_secret`. Intended for trusted internal services, local stacks, and the quickstart — **not** for production payer-to-payer or provider integrations, which must use SMART Backend Services (asymmetric).
### Client registration
```json
PUT /Client/my-service
Content-Type: application/json
{
"resourceType": "Client",
"id": "my-service",
"active": true,
"grant_types": ["client_credentials"],
"secret": ""
}
```
An access policy must grant the client access to whatever resources it will read or write.
### Token request
{% tabs %}
{% tab title="Request (form body)" %}
```http
POST /auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=my-service
&client_secret=
```
{% endtab %}
{% tab title="Request (Basic auth)" %}
```http
POST /auth/token
Authorization: Basic )>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
```
{% endtab %}
{% tab title="Response" %}
```json
{
"token_type": "Bearer",
"access_token": "",
"need_patient_banner": true
}
```
{% endtab %}
{% endtabs %}
Use the returned `access_token` as `Authorization: Bearer ` on any FHIR request.
## Scopes
Payerbox supports both SMART v1 and v2 scope syntax (capabilities `permission-v1` and `permission-v2` are both advertised).
| Context | Use |
|---|---|
| `patient/` | Member-scoped (SMART App Launch). The access token's `context.patient` claim identifies which member. |
| `system/` | System-level (Backend Services / Client Credentials). No per-member filter; access is governed by access policies, attribution, and consent. |
| `user/` | User-scoped — used when a logged-in clinician launches an app. |
Permissions:
- **v1** — `read`, `write`, `*` (e.g. `patient/*.read`, `system/Claim.write`).
- **v2** — granular CRUDS letters: `c` (create), `r` (read), `u` (update), `d` (delete), `s` (search). Wildcard `*` allowed (e.g. `patient/*.cruds`, `system/Patient.rs`).
### Scopes with search parameters (v2)
Append a FHIR search query to a v2 read/search scope to narrow what the token can pull:
```
patient/Observation.rs?status=final
```
Aidbox auto-applies the filter to every search and read under that scope. Disallowed inside `c` / `u` / `d` permissions and disallowed with `_include`, `_revinclude`, `_has`, `_assoc`, `_with`.
### Common scope sets
| Surface | Recommended scopes |
|---|---|
| Patient Access app (read-only) | `openid fhirUser patient/*.read offline_access` |
| Provider Access (Backend Services) | `system/*.read` |
| Payer-to-Payer (Backend Services) | `system/*.read` |
| PAS (Backend Services) | `system/Claim.cu system/ClaimResponse.r` |
Full inventory of what a given deployment exposes is in the SMART configuration document's `scopes_supported`.
## Common errors
HTTP OAuth error Cause 400 invalid_requestMissing or malformed parameter 400 invalid_grantAuthorization code expired, already used, or refresh token invalid 400 invalid_clientUnknown client_id, wrong secret, or client assertion signature did not verify against the registered JWKS 400 invalid_scopeRequested scope not allowed for this client 401 invalid_tokenAccess token expired, revoked, or signature invalid 403 insufficient_scopeToken lacks the required scope for the resource (returned as OperationOutcome from /fhir)