Hermos API
Concepts

Authentication

Company credentials and request authentication.

Company API keys use the HTTP Authorization header:

Authorization: Bearer <company-api-key>

Use exactly one space after Bearer, followed by one credential without whitespace. The scheme is case-insensitive. Treat credentials as opaque secrets.

Keys are never accepted in the query string. Query names api_key, apikey, api-key, x-api-key, access_token, authorization, bearer, secret, token, and key are rejected, including empty values. Matching is case-insensitive after URL decoding.

A verified company credential establishes a principal, company, and mode. Test mode is livemode: false; live mode is livemode: true. The verified identity determines mode; sending a header does not change the verified credential's mode. Tenant idempotency records and signed pagination cursors bind to company and mode.

Hosted checkout keys

POST /v1/hosted_checkout_keys/ensure issues or reuses a publishable catalog:read key for the selected company and mode. It requires a person member with mode access, keys:write, fresh step-up, and an active company. Test keys start with hms_pk_test_; live keys start with hms_pk_live_.

GET /v1/hosted_checkout_keys/{reference} is public. Its mode query parameter is test (the default) or live; by=company_id selects lookup by company UUID. Responses use Cache-Control: no-store.

Live issuance and discovery require both HERMOS_LIVE_HOSTED_CHECKOUT=enabled (exactly) and HERMOS_ENV=production. Staging, local, and development never issue or discover live hosted keys, even with the flag set. Disabled live issuance returns 403; disabled live discovery returns the same 404 as a missing key.

The flag controls issuance and discovery only. An already issued live key keeps working with the flag off. Revoke the key to stop its use. Readiness belongs to the product at sale time, not key issuance: a new checkout checks its payment setup and processor account. Rechecking readiness atomically at submission is separate work (HERM-947 PR 1b).

Test and live hosted keys coexist for the same company, with one key per mode. HERM-73 may enable the live flag only after both PR 1b (submission readiness admission) and PR 3 (Migration B) are deployed.

GET /v1/openapi.json is public. GET /v1/me/companies uses the signed-in member's session cookie, as declared in its API reference. A member session has no selected company or mode. An explicit Authorization header selects Bearer authentication without falling back to a cookie.

GET /v1/company_references/{reference} also requires a member session cookie, but no company membership or company/mode headers. Bearer credentials and platform staff are refused. References must contain 1–80 lowercase ASCII letters, digits, underscores or hyphens; malformed values return 400 without a lookup. A successful response is exactly {"reference":"acme","available":true}. Taken and reserved names return available: false, without company or owner information. Occupied references include inactive and unpublished companies. Successful responses use Cache-Control: no-store. The companyReference bucket allows 60 checks per stable member per aligned minute per API instance, shared across sessions and references. A 429 carries the rate-limit and Retry-After headers; a failed lookup returns 503. Availability is advisory: POST creation remains authoritative and a reference claimed in the meantime returns 422 with company_reference_taken.

Team members and roles

The members:read capability allows a signed-in member to read the company's team members, invitations, and role catalogue. It discloses teammates' login email addresses and two-factor authentication state. Only Owner and Admin can read these details; custom roles cannot be granted this capability.

GET /v1/team_members and GET /v1/team_invites accept limit (default 50, maximum 100) and an opaque cursor. Follow next_cursor while has_more is true. A member whose login identity is missing is omitted; paging still advances past that row.

GET /v1/roles includes archived custom roles still assigned to active members or pending invitations, with archived: true. Unheld archived roles are omitted. Archived roles are shown for existing assignments. In the change-roles drawer, they can be removed but cannot be added.

Checkout hand-offs

RoutePrincipalScope
POST /v1/checkout_handoffsSecret or restricted keybilling:write
POST /v1/checkout_handoffs/abandonSecret key onlybilling:write
POST /v1/checkout_handoffs/{id}/abandonSecret key onlybilling:write

Abandonment is company- and mode-scoped. It returns only the checkout ID, terminal status and terminal timestamp. Repeating the instance-ID form on a terminal checkout is a no-op. An unresolved submission returns 409 conflict with submission_in_progress; wait for reconciliation.

A plain checkout open has no organisation subject. It starts a personal form after an organisation purchase; plain buy-again also has no subject. Use the organisation's hand-off to resume its receipt. A conflicting live checkout returns checkout_already_open; a merchant may abandon it when no submission is in flight before opening for a different subject.

To recover a stuck subject checkout from your server, send POST /v1/checkout_handoffs/abandon with { "subject_ref": "org:example", "product": "your-product" }. No browser cookie or instance ID is required. The product's default offer and subject must match one live checkout in your company and mode. No match returns 404; multiple matches return 409 multiple_checkouts_open. The instance-ID form remains available and returns 200 unchanged for terminal instances.

On this page