Authentication quickstart

Four steps from a client-credentials pair to your first authenticated read.

POST {{OAUTH_TOKEN_URL}}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{CLIENT_ID}}
&client_secret={{CLIENT_SECRET}}

GET {{API_BASE_URL}}/api/capabilities
Authorization: Bearer <token>

# 200
{
  "capabilities": [
    "patients:read",
    "slots:read",
    "appointments:book"
  ]
}

Connect via MCPnew

Call the same operations as tools over the Model Context Protocol — for agent runtimes that connect and invoke, instead of composing HTTP requests.

POST {{OAUTH_TOKEN_URL}}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{CLIENT_ID}}
&client_secret={{CLIENT_SECRET}}

# 200 — send access_token as the bearer below
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 450
}

{
  "type": "url",
  "url": "{{MCP_BASE_URL}}/mcp",
  "name": "rsi",
  "authorization_token": "<bearer token>"
}

# any MCP client library does this for you — shown raw for clarity
curl -X POST {{MCP_BASE_URL}}/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# → SSE frame:  data: {"result":{"tools":[ …22 tools… ]}}

# 1) call the tool — no confirmationToken
book_appointment(patientId, slotId)
# → non-error result: "CONFIRMATION REQUIRED … confirmationToken=…"

# 2) same tool, same args, plus the token → executes
book_appointment(patientId, slotId, confirmationToken)

The confirmation protocol 428

Every mutation is two-phase: the API returns a challenge, then an identical confirming request commits it.

This is a safety gate between your agent and the API — it forces a mutation to be committed deliberately, in two steps, so a booking, cancel, or patient write can never fire on a single (possibly mistaken) call. Because writes on your client require confirmation, your first attempt returns 428 with a confirmationToken and a readBack instead of performing the action. You resend the identical body to the same URL with that token, and the phase flips from challenge to commit. No separate endpoint, no state to negotiate — the token's presence is the only thing that changes. Getting the patient's go-ahead happens before this and is your responsibility; the API neither sees nor verifies that conversation.

Every write is two-phase — there are no exceptions: book an appointment, cancel an appointment, confirm attendance, create a patient, update a patient. Reads are always a single call.

The exchange, end to end

Two steps, both machine-to-machine

The token, threaded verbatim

The token is bound to a fingerprint of your exact fields. Watch the highlighted value — it is minted in the 428 response and carried, character for character, into the confirming request.

POST /api/appointments
Authorization: Bearer <token>

{ "patientId": "{patientId}", "slotId": "{slotId}" }

{
  "code": "confirmation_required",
  "confirmationToken": "{confirmationToken}",
  "expiresAt": "2026-07-05T18:05:00Z",
  "readBack": { "patientId": "{patientId}", "slotId": "{slotId}" }
}

POST /api/appointments
Authorization: Bearer <token>

{ "patientId": "{patientId}", "slotId": "{slotId}",
  "confirmationToken": "{confirmationToken}" }

# 201 → { "appointmentId": "{appointmentId}" }

Edge cases

Codes link to their page in the problem registry.

Booking playbook

The scripted, test-verified call flow — turning a patient's words into four ids and a confirmed slot.

Slot search needs all four of providerId, locationId, visitTypeId, and procedureId — none is optional — plus a date window of 14 days or less. So most of the work is resolving the patient's phrases ("Dr Smith, Downtown, for acne") into those ids — opaque encoded strings — against the directory endpoints, by name. Never relay any of these ids to the patient.

Parameters — the match request

Confirm the patient's identity before disclosing anything. All four fields are required; phone needs at least four digits.

A match returns one patient (its id is your patientId); a 404 means you have not verified them — offer to create a new patient or take a message, never read back records.

SKILL.md

The operating manual for agents that compose HTTP requests themselves — hand it to the model and it holds the whole contract. Runtime speaks MCP instead? Connect via MCP.

SKILL.md is the machine-facing guide for an LLM agent in a live patient conversation, acting for one medical practice. It packs the whole flow — OAuth setup, the id-acquisition the slot search requires, the mandatory two-phase 428 exchange, the full endpoint surface, every error code with recovery steps, and the HIPAA and conversational rules — into one document written to be read by the model itself.

Two rules dominate everything

What it covers

• Setup — base URL, OAuth2 client-credentials, and the /api/capabilities trust check.
• The conversation playbook — the canonical 8-step booking dialogue, plus cancel, attendance confirm, and patient create/update.
• Endpoint reference — every path, scope, parameter, and response shape, all camelCase JSON with null fields omitted.
• The 428 protocol — the exchange and all its edge cases: byte-identical resend, safe replay, expiry, confirmation_incomplete recovery.
• Error handling — the full code table with per-code recovery steps.
• Conversational & HIPAA rules — identity-first, never speak ids, read back before every commit, one clarifying question at a time.

Error handling

Every error is an RFC 7807 problem+json body with a stable machine code. Match on the code, never the prose.

Errors carry a type URL, a title, an HTTP status, a stable code, and a requestId, alongside an X-RSI-TRACE-ID response header. The title and detail are human strings and may carry no PHI by design — branch on code. On any escalation, quote the requestId so support can trace it; never read it to the patient.

{
  "type": "https://docs.redspotinteractive.com/errors.html#validation",
  "title": "One or more parameters are invalid.",
  "status": 422,
  "code": "validation",
  "errors": [ { "field": "to", "rule": "maxWindow", "message": "Window must be ≤ 14 days." } ],
  "requestId": "req_5f2c9a"
}

Problem registry

Every error body carries a type URL that resolves to the code's entry in the error catalog.

Branch your handling on the stable code, not on the HTTP status alone — several codes share a status (three distinct 409s, two 403s). The recovery column is the action a LLM agent should take on the call.

No codes match that filter.

confirmation_mismatch 409

The confirming request's body differs from the intent that was challenged, so nothing executes.

{
  "type": "https://docs.redspotinteractive.com/errors.html#confirmation_mismatch",
  "title": "The confirmation does not match the challenged request.",
  "status": 409,
  "code": "confirmation_mismatch",
  "requestId": "req_5f2c9a1b"
}

Why this happens

• A business field changed between the challenge and the confirm — the token is bound to a fingerprint of your exact fields, so any drift invalidates it.
• A second, different intent reused a token that was minted for the first one.

Nothing executes, and the original challenged intent stays valid until its expiresAt passes.

How to resolve

Related

• The 428 confirmation protocol — the full exchange and its edge cases.
• confirmation_incomplete — token consumed, outcome unknown (a different 409).
• slot_unavailable — the slot was taken between search and book.

API reference

The full v1 endpoint surface — providers, patients, slots, appointments, and the directory.

Downloads

Everything you need to wire an integration or brief a LLM-agent vendor.