JSON in. JSON out.

How it fits together

Your company. Your customer. Their login.

Every call runs on one path: your tenant, one of your customers, and that customer’s saved login to one system. Connections, credentials and usage stay on that path. One customer’s session is never shared with another.

Calls that act on one customer take organization_id. A tenant key must send it. A key pinned to one organization may leave it out.

GET /v1/organizations is cursor-paginated: 50 per page by default, up to 100 with limit. Filter by name with q and pass next_cursor back as cursor. POST /v1/organizations/import adds up to 500 at once.

Base URLs

REST for software. MCP for agents.

Authenticate

A key, or a sign-in.

• Software. Authorization: Bearer pk_live_… Minted in the console. Shown once.
• Agents. An OAuth access token, sent as Authorization: Bearer vat_live_…. Unauthenticated MCP returns 401 with OAuth discovery. The user signs in on the console and pins one organization.
• Scope. Every key belongs to your tenant. A tenant key works across all your organizations. An organization key is pinned to one customer.
• Check a key. GET /v1/me returns the key’s org_id (null for a tenant key), its scopes, and its caller_id.
• Missing scope. 403 insufficient_scope names the scope the key lacks in error.required_scope. Webhooks need a tenant key with the vault scope. Attested approvals need portal_login_mutation.

Connect a customer’s system

They sign in once. The password stays in the vault.

Your product collects the username and password and sends them to Veraxus. If the system asks for a verification code, your customer pastes it into your screen. After that, every read reuses the saved login and never posts the password.

connected is a legacy alias of ready. New code should switch on ready.

POST https://api.veraxus.ai/v1/portal/connect
Authorization: Bearer pk_live_…
Idempotency-Key: ••••••••••••••••
// body: organization_id and the system id. See the spec.

// 200
{
  "ok": true,
  "status": "needs_code",
  "message": "Enter the one-time code.",
  "complete_with": "complete_portal_mfa",
  "generation": 1,
  "client_reference": null
}

POST https://api.veraxus.ai/v1/portal/mfa
Authorization: Bearer pk_live_…
// body: organization_id, the system id and the code

// 200
{
  "ok": true,
  "status": "ready",
  "message": "Login saved."
}

POST https://api.veraxus.ai/v1/portal/connect
Authorization: Bearer pk_live_…

// 503, with a Retry-After header
{
  "error": {
    "code": "portal_outage",
    "message": "…",
    "retryable": true,
    "retry_after": …
  }
}

Request bodies and every field are in the spec.

Read, write, export

Each system publishes its operations.

A connected system lists what it can do, each operation marked read or write. Reads and writes go through the same call. Today this interface serves connected cloud practice-management software.

Connect these systems with the same POST /v1/portal/connect, naming the system by its id from GET /v1/pms/vendors. There is no separate connect route. PUT /v1/credentials also takes portal_url, your customer’s own address on that system.

GET https://api.veraxus.ai/v1/pms/{vendor}/operations
Authorization: Bearer pk_live_…

// 200
{
  "operations": [{
    "name": "••••",
    "kind": "read",
    "summary": "••••",
    "input": { … },
    "input_schema": { … }
  }]
}

POST https://api.veraxus.ai/v1/pms/{vendor}/execute/{operation}
Authorization: Bearer pk_live_…

{
  "organization_id": "org_…",
  "input": { … }
}

// 200
{
  "status": "ok",
  "operation": "••••",
  "kind": "read",
  "projected": { … },
  "raw": { … },
  "http_status": 200,
  "hops": [ … ],
  "realm": "••••",
  "client_reference": null
}

POST https://api.veraxus.ai/v1/pms/{vendor}/execute/{operation}
Authorization: Bearer pk_live_…
Idempotency-Key: ••••••••••••••••

{
  "organization_id": "org_…",
  "input": { … },
  "attestation": {
    "actor_user_id": "••••",
    "consent_session_id": "••••",
    "consented_at": "2026-10-14T15:04:05Z"
  }
}

// 502 unknown_outcome: do not resend. Read first.

Webhooks

Signed events instead of polling.

Register an HTTPS URL with POST /v1/webhooks, using a tenant key with the vault scope. Veraxus POSTs JSON signed with HMAC-SHA256. The signing secret (whsec_…) is returned once, on create and on rotate-secret.

• Headers. Veraxus-Event, Veraxus-Delivery, and Veraxus-Signature: t=<unix>,v1=<hex>, an HMAC over ${t}.${body}.
• Freshness. Reject a timestamp more than five minutes from your clock.
• Rotation. After rotate-secret, both secrets work for 24 hours and each delivery carries two v1 values. Accept any that matches the secret you hold.
• Delivery. 10-second timeout. A 3xx is a failure. Bodies are capped at 256 KiB. Retries at 1m, 5m, 30m, 2h and 12h, then dead.
• Deactivation. 20 consecutive failures deactivate the endpoint and emit webhook.deactivated.
• Duplicates. Delivery is at least once. Deduplicate by payload.id.
• Scope. Omit organization_id for a tenant-wide default. Set it to override the default for one organization. Scope is fixed at creation.

Events include portal_login.status_changed (Connect, code and session-health changes), portal_login.state_changed, portal_login.desk_changed, webhook.test and webhook.deactivated. The full list is the events enum in the spec.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, body, nowSec = Math.floor(Date.now() / 1000)) {
  const v1s = [];
  let t;
  for (const piece of header.split(",")) {
    const i = piece.indexOf("=");
    const k = piece.slice(0, i).trim();
    const v = piece.slice(i + 1).trim();
    if (k === "t") t = v;
    else if (k === "v1") v1s.push(v);
  }
  if (!t || Math.abs(nowSec - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return v1s.some((v1) => timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(v1, "utf8")));
}

Errors

Branch on the code. Show the message.

Every non-2xx response has the same shape. Branch on error.code, a stable machine string. Show error.message to a person. Retry only when error.retryable is true, after error.retry_after seconds.

{
  "error": {
    "code": "insufficient_scope",          // branch on this
    "message": "…",                       // show this to a person
    "retryable": false,
    "retry_after": null,
    "required_scope": "portal_login_mutation"
  }
}

503 responses also carry a Retry-After header. The full code list, with HTTP status and retry flag for each, is in the spec.

Reference

The spec is the contract.

Machine spec (OpenAPI 3.1): api.veraxus.ai/v1/openapi.json. HTML reference: api.veraxus.ai/v1/reference. Agents connect at api.veraxus.ai/mcp. Spec is public. Calls are not.