API documentation

Authentication

Send an organization API key as a bearer token: Authorization: Bearer mya_live_… Keys are created by owners and admins, on the Business plan and up, and are shown once. Each key acts for its own organization only, within the scopes you give it.

Scopes a key can have:

• org:read
• org:write
• members:read
• members:write
• files:read
• contracts:read
• approvals:read
• webhooks:read
• webhooks:write

curl https://<your-host>/api/v1/contracts?limit=10 \
  -H "Authorization: Bearer mya_live_…"

curl -X POST https://<your-host>/api/v1/org/webhooks \
  -H "Authorization: Bearer mya_live_…" \
  -H "Idempotency-Key: 6f0d2c1e-hooks-1" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/mya","events":["approval.requested","contract.closed"]}'

Errors

Errors are JSON with an error object holding a code, a message, optional details and a request_id. Quote the request_id when you contact support. The codes are:

• auth_required
• step_up_required
• forbidden
• not_found
• plan_limit
• validation
• approval_required
• contract_inactive
• connection_missing
• rate_limited
• vault_unavailable
• billing_unavailable
• model_unavailable
• queue_unavailable
• two_person_required
• conflict
• provider_unavailable
• budget_exceeded
• internal

Pagination

Lists return up to limit items (25 by default, 100 at most) and a next_cursor. Pass it back as cursor to get the next page; when next_cursor is null you have everything. Cursors are opaque.

Idempotency

Send an Idempotency-Key header with any POST to retry it safely. The first answer is kept and replayed for the same key and request (the Idempotent-Replayed header says so). The same key with a different request is refused. Secrets shown once are never replayed.

Rate limits

Each API key may make a set number of requests per minute. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get 429 rate_limited with Retry-After.

Webhooks

Register an HTTPS endpoint and choose events. Each delivery is a POST with the event as JSON and three headers: MYA-Event, MYA-Event-Id and MYA-Signature. Answer with a 2xx within the timeout; anything else is retried with growing delays, and an endpoint that keeps failing is switched off. Verify the signature on the raw body before trusting it:

• approval.requestedAn agent needs a decision
• deliverable.readyA deliverable is ready for review or delivered
• contract.status_changedA contract changed status
• report.readyA report is ready
• connection.expiringA connection expires soon
• contract.closedA contract closed, with its certificate link

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

// rawBody: the request body exactly as received (a string, before JSON.parse)
export function verifyMyaWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === 32 && timingSafeEqual(given, Buffer.from(expected, "hex"));
}

API reference