API Reference

API Overview

The RxVault verification API enables partners to validate whether a customer has a valid, non‑expired prescription for a supported category. This API is intentionally narrow: it returns only yes/no + status, and uses short‑lived tokens for checkout flows. It does not expose full medical records.

Base URL

rxvault.org

Use HTTPS only

Partner API

/api/v1/partner

Server-to-server

Checkout redirect

/verify

Returns short-lived rxv

Integration patterns

Recommended flow

Recommended: use the redirect flow so you never expose partner keys in the browser. Then validate the returned rxv token from your backend using the partner API.

Redirect verification: customer enters code → RxVault redirects back with rxv or rxv_error.
Partner API: server‑to‑server endpoints protected by partner keys + scopes.

Quick start

Redirect URL

GET https://rxvault.org/verify?code=<RX_U14_CODE>&return=<YOUR_RETURN_URL>

Redirect verify

No partner keys in browser

Request

GET /verify?code=<RX_U14_CODE>&return=<YOUR_RETURN_URL>

Redirect back

Success: ?rxv=<token>
Failure: ?rxv_error=invalid or ?rxv_error=expired

Partner: verify token

Scope: rx.token.verify

Request

POST /api/v1/partner/verify-token
Authorization: Bearer <partner_key>
Content-Type: application/json

{ "request_id": "client-uuid-123", "token": "<rxv>" }

Partner: verify code

Scope: rx.verify

Request

POST /api/v1/partner/verify
Authorization: Bearer <partner_key>
Content-Type: application/json

{ "request_id": "client-uuid-123", "code": "<RX_U14_CODE>" }

Scopes

Authorization

rx.verify: call /api/v1/partner/verify
rx.token.verify: call /api/v1/partner/verify-token

Production configuration

VPS shared config.env

Allowlist redirect return URLs

RXVAULT_RETURN_URL_ALLOWLIST=https://rxvault.org,https://yourstore.com

Token signing (rxv)

RXVAULT_VERIFY_SECRET=<long_random_secret>
RXVAULT_VERIFY_TTL_SECONDS=600

Partner keys + scopes

RXVAULT_PARTNER_KEYS_JSON=[
  {"id":"keystone","name":"Keystone Optical","key":"pk_live_xxx","scopes":["rx.verify","rx.token.verify"]}
]