Passage API · Contract 0.3.0

Move an authorization through retail—without moving the clinical record.

Passage gives pharmacy, retail, and ecommerce systems one stable contract for product lookup, non-consuming verification, atomic redemption, reversal, and minimized status.

Start integrating Explore the API

The Passage boundary

A partner learns whether an authorization permits a transaction—not the consumer’s questionnaire answers or the clinical rationale behind the decision.

Receives: Signed authorization, product, partner, and transaction context
Returns: Permitted state, reason code, identifiers, and remaining use
Never returns: Clinical answers, conditions, laboratory values, or evaluated rules

Quickstart

A typical point-of-sale integration has three deliberate steps. Verification never consumes an authorization; redemption does.

1
Request a scoped token
Exchange the sandbox client credential using OAuth 2.0 client credentials. Request only the scopes your integration needs.
2
Verify the authorization
Send the authorization token with product, partner, location, channel, quantity, and transaction context.
3
Redeem atomically
After the product is available for handoff, redeem with a unique idempotency key. Passage rejects replay without creating a second use.

POST /v1/authorizations/verify

{
  "authorization": { "token": "cgp1.synthetic..." },
  "product": { "ndc": "00000-0000-00" },
  "partner": {
    "partner_id": "BWPG-001",
    "location_id": "BWPG-1842"
  },
  "transaction": {
    "transaction_id": "POS-8392841",
    "channel": "PHYSICAL_RETAIL",
    "quantity": 1
  }
}

Authentication

Partner integrations use short-lived bearer tokens issued to registered, environment-bound clients. Sandbox and production credentials are separate, revocable, rotatable, scoped, and auditable.

ScopePermitted action

authorization:verifyCheck permission without consumption

authorization:redeemRecord product handoff atomically

authorization:reverseReverse an eligible redemption

authorization:statusRead a minimized authorization state

Credential rule: Never place a Passage client secret in browser code, a mobile application, screenshots, source control, or support messages.

Integration model

Gatehouse decides. Passage authorizes. Retailers verify. These boundaries stay separate so each system receives only what it needs.

Approved sourceSigned fulfillment assertion

PassageNetwork authorization

Trading partnerVerify, redeem, reverse

Stable canonical contract, adaptable external rail

Passage keeps authorization semantics independent from any future NCPDP, chain-retailer, ecommerce, or pharmacy-management schema. A versioned adapter translates the partner’s external message without importing clinical qualification logic into the integration layer.

Verification is not redemption

Verify

Answers whether the authorization is currently valid for the product and transaction context.

Does not consume use
Safe before checkout commitment
Returns a verification identifier

Redeem

Records that the authorization was actually used to make the product available.

Atomic state change
Requires an idempotency key
Creates durable transaction lineage

Idempotency and retries

Every state-changing partner request must include a stable Idempotency-Key. Reuse the same key when retrying the same logical transaction after a timeout. Generate a new key only for a genuinely new transaction.

Timeout before responseRetry the identical request with the identical key.

Payload changedDo not reuse the prior key; correct the request and create a new transaction.

Unknown outcomeCheck status or retry safely. Never assume a timeout means redemption failed.

Errors and reason codes

HTTP status communicates protocol handling. The canonical reason code communicates the authorization outcome. A technically successful verification can still return a business result such as ALREADY_REDEEMED or WRONG_PRODUCT.

Authorization state

AUTHORIZATION_EXPIREDAUTHORIZATION_REVOKEDALREADY_REDEEMED

Transaction mismatch

WRONG_PRODUCTQUANTITY_LIMIT_EXCEEDEDCHANNEL_NOT_PERMITTED

Fail-closed operation

REGISTRY_STALEDEPENDENCY_FAILURETECHNICAL_FAILURE

See the complete machine-readable reason-code enum →

Sandbox

The partner sandbox uses synthetic products, authorizations, locations, and transaction identifiers. Sandbox artifacts are distinguishable from production and must never be accepted in a production trading profile.

Base URLhttps://sandbox-api.cleargateaccess.com/passage

Documentation available. Credential issuance and the interactive sandbox will be enabled during partner onboarding.

Integration checklist

Use an environment-specific registered client.
Store client credentials only in a server-side secret manager.
Implement token renewal before expiration.
Keep verification separate from redemption.
Persist Passage correlation and transaction identifiers.
Retry state changes with the original idempotency key.
Handle every documented canonical reason code fail-closed.
Pass replay, expiry, suspension, wrong-product, and dependency-failure certification tests.