An agent-native prior authorization protocol and TypeScript SDK.

x278 turns prior authorization into a typed exchange between provider-side and payer-side agents. A provider agent submits a structured request; a payer agent returns an actionable determination; and the workflow continues without restarting the queue.

Install SDK Read the Spec

$npm install @backwork/x278

Read the announcement on the Backwork blog

Built for the authorization workflows agents are about to run.

x278 models the prior authorization lifecycle as four explicit states: approved, denied, info-needed, and pended. Each non-approval tells the provider agent what to do next, whether that means attaching evidence, awaiting review, correcting the request, or starting an appeal.

Structured requests

Submit patient, provider, service, diagnosis, urgency, and supporting information in a typed protocol shape.

Actionable determinations

Receive approved, denied, info-needed, or pended responses with explicit next actions.

Retry without restart

Attach missing documentation and resume the same authorization context using the same authId.

Signed receipts

Verify terminal determinations and keep an auditable record of what was returned, when, and by which rule set.

FHIR-aware

Map x278 requests and determinations onto FHIR/PAS-style resources while keeping the SDK surface agent-friendly.

Start with the reference payer

Start with the in-memory reference payer, then swap in the HTTP transport when you are ready to test against an x278-compatible endpoint.

reference-payer.ts

import {
  createMockX278Client,
  kneeReplacementMissingDocs
} from "@backwork/x278";

const client = createMockX278Client({
  collectEvidence: (_request, requirements) =>
    requirements.map((requirement) => ({
      id: requirement.id,
      value: `chart evidence for ${requirement.id}`,
      source: "chart"
    }))
});

const trace = await client.requestWithTrace(kneeReplacementMissingDocs);

console.log(trace.steps.map((step) => step.status));
// ["info-needed", "approved"]

Use the production HTTP client for real endpoint integration.

http-client.ts

import { createX278HttpClient } from "@backwork/x278/http";

const client = createX278HttpClient({
  baseUrl: "https://payer.example/x278",
  bearerToken: process.env.X278_BEARER_TOKEN,
  collectEvidence
});

const capabilities = await client.capabilities();
const determination = await client.request(authorizationRequest);

Protocol states

approved: Authorization approved by rules or reviewer.
denied: Request denied with a coded reason and appeal path.
info-needed: Specific documentation is required. Attach evidence and resume the same authId.
pended: The request was accepted but is not final. Await the returned subscription or update handle.
error: The exchange was malformed or unprocessable.

The SDK includes conformance tests, package export validation, Docker-based realistic scenarios, HAPI FHIR validation, and live agent tests using the OpenAI Agents SDK and Anthropic TypeScript SDK.

Links

x278 is a proposed protocol and reference implementation. It is not a certified payer integration, a substitute for Da Vinci PAS conformance testing, or legal or compliance advice.