Business Management (3.0.0-preview)

Overview

The Business Management API V3 is Altegio's next-generation public REST API. This document is a preview of the V3 contract: it describes the target API surface so partners and tooling can review it before the endpoints go live.

Preview status — please read first:

• This is a contract preview, not a live production API. The endpoint surface is not deployed yet; try-it consoles and production calls are unavailable.
• Paths, schemas, and field names may change before the contract freeze without backward-compatibility guarantees.
• Every operation carries an x-altegio-status. Three values are defined: planned — designed, not scheduled for the first production release; preview — contract published for review, not deployed; available — live in production and covered by the October 2026 release promise. Today every operation is preview — none of them is deployed yet. The October release covers only operations marked available, so publishing the full target surface here is not a promise that all of it ships at once. available is enforced by CI in biz.erp: an available operation without a registered route fails the OpenAPI conformance gate.
• Where a design decision is still pending, the affected element also carries x-altegio-assumption describing the open question.

Base URL (resource API): https://api.alteg.io/api/v3

All resources are under /api/v3 and scoped to a Location: /api/v3/locations/{location_id}/.... The location_id in the path is verified against the credential used for the call — a Location the credential cannot access responds with 404. OAuth and discovery endpoints live on the authorization host root https://api.alteg.io (no /api/v3 prefix) — see the Authorization tag.

Canonical terms. V3 uses one public name per entity:

Response format. V3 is flat resource REST. Single resources are plain JSON objects with integer id and a string object type marker. Lists use one predictable envelope. V3 does not use JSON:API (data.attributes) or wrapper envelopes such as {success,data,meta} envelopes.

Object types. Every resource declares its kind in the object field — the full dictionary of this preview:

Authorization

V3 accepts exactly one credential shape on every call:

Tokens are opaque strings — never parse or decode them. There is no public password grant: applications never collect Altegio passwords. Three kinds of credential exist. The first two ship in the first iteration; the third is planned for the second delivery.

Access model

Every request is resolved through the same runtime formula:

• A scope opens an endpoint; the rights behind the credential then decide which rows and fields are visible or writable. Having a scope does not bypass the permission system of the business, and those rights can change without you: when a business admin narrows them, the credential narrows with them on the next request.
• Location binding: resources live under /api/v3/locations/{location_id}/...; the location_id in the route is checked against the token's grants. A foreign Location returns 404 — existence is not leaked.
• Scopes are credential-class bounded. A credential can use only scopes allowed for its kind. An API key and a user-delegated token act with the live permissions of the author or the consenting user, read on every request with a cache of at most one minute; an installation token acts with the permissions granted to the installation. Revocation is never cached: a revoked token fails on the very next request.
• No step-up in this preview. Dangerous operations in this preview are protected by explicit scopes, the subject's business permissions, audit, and rate limits. A future human-confirmation flow will be added only with a complete challenge contract.

Conventions

• Resource shape: a flat JSON object with integer id, a string object type marker, and domain fields. No envelopes, no prefixes on ids.
• List shape: {"object": "list", "data": [...], "has_more": false, "next_cursor": null}. Pagination is cursor-based: pass limit and the next_cursor value from the previous page as cursor. Cursors are opaque, expire one hour after the response that issued them (every page issues a fresh cursor), and only work for the credential, list, ordering and filter set that produced them. Paging is stable for rows whose ordering columns do not change between pages; a row whose ordering column was updated meanwhile (for example a moved appointment) may be skipped or returned twice, and a row created while you page may be missing from this pass if it sorts before the current position. Page/offset pagination does not exist in V3.
• Field naming: all JSON fields, query parameters, and path segments are snake_case; operationId values are lowerCamelCase.
• Dates and times: RFC 3339 everywhere.
  • Audit instants (created_at, updated_at, cancelled_at) are UTC: 2026-07-14T09:20:31Z.
  • Appointment times (starts_at, ends_at) carry the Location's local UTC offset: 2026-07-09T11:30:00+01:00.
  • Date-only values are YYYY-MM-DD; wall-clock times (working hours, schedule slots) are HH:MM in the Location's timezone.
  • Naive datetimes and Unix timestamps never appear.
• Money: integer minor units of the Location currency (1250 = one thousand two hundred fifty minor units). The currency (ISO 4217) is server-controlled, read-only, and repeated in money-carrying resources. Monetary field names use the _minor suffix. Floating-point amounts are rejected.
• Partial updates: PATCH bodies are application/merge-patch+json. A missing field means "leave unchanged"; null clears a nullable field; arrays are cleared with an explicit [], never null. Clearing a non-nullable field fails with 422 field_not_nullable; writing a read-only field fails with 422 field_immutable. Unknown request fields are rejected; unknown response fields must be ignored by clients.
• expand[]: related objects are returned as ids by default. Documented relations can be expanded one level deep with expand[]=<relation> (allowlist per endpoint, depth 1). An unknown expand value fails with 422. Expansion never bypasses field-level permissions — see PII below.

Errors

Every error from a resource operation is application/problem+json (RFC 9457 hybrid):

The OAuth protocol and discovery endpoints are the one exception: POST /oauth/token, POST /oauth/revoke, POST /oauth/register and /.well-known/* return the standard OAuth 2.0 error object ({"error": "…", "error_description": "…"}) defined by RFC 6749, 7009 and 7591 — not application/problem+json. The GET /oauth/authorize browser flow reports errors on its own HTML page or as OAuth error parameters on the redirect (error, error_description, state, iss), never as JSON. GET /oauth/accessible-resources is the opposite case: despite the path it is an ordinary Bearer-authed read and uses application/problem+json like the rest of the API.

Everything else in this section (stable codes, field-level errors[], request correlation) describes resource operations. Rate limiting is the one rule both surfaces share: every 429 carries Retry-After.

Two conventions keep this table stable:

• Promotion. Only public machine-readable codes that clients are expected to branch on enter this table. Adding a code means editing this table and registering it in the biz.erp V3ProblemCatalog in the same cycle — the CI conformance gate keeps both sides in sync. Internal exceptions are never promoted implicitly: an unregistered code degrades to the generic status default and nothing internal leaks.
• Naming. invalid_* means the supplied value does not exist or fails validation (invalid_token, invalid_city, invalid_business_type); unsupported_* means the value is valid but not supported by the product or policy (unsupported_country, unsupported_media_type, unsupported_token_subject).

Stable codes used by this preview (branch on these; domain codes below are equally stable):

Field-level codes inside errors[] (not top-level code) include expired_cursor, invalid_cursor, foreign_cursor, filter_changed, and validation codes such as invalid_datetime.

Example — validation failure (422):

Example — stale optimistic-concurrency version (412):

Retry guidance depends on the code, not on a generic flag: fix the request on 422; re-read the resource on 412; retry the same Idempotency-Key after Retry-After on 409 idempotency_request_in_progress; back off on 429/503; after a network timeout on a create or command, retry only with the same Idempotency-Key.

Idempotency & concurrency

Both mechanisms below belong to the contract but are not part of the first iteration: no first-iteration operation requires Idempotency-Key or If-Match, and reads do not return ETag yet. They arrive together with the operations that need them (appointment creation, payments, concurrent appointment edits) and before contract freeze; operations that already carry the headers in this document are marked planned.

Idempotency-Key will be required on every POST create and command where a retry could duplicate a side effect (creating appointments, clients, payments; cancel/status commands).

• Generate a unique key per logical request (UUID recommended).
• A retry with the same key and the same body returns the original result — including the case where the first attempt committed but its response was lost.
• The same key with a different body fails with 409 idempotency_key_reused.
• A concurrent duplicate fails with 409 idempotency_request_in_progress and Retry-After.
• Keys are retained for at least 24 hours, scoped to the credential, Location (when present), and operation. After expiry the same key value may start a new logical request (it is not idempotency_key_reused).
• If the idempotency store is unavailable, the write is not performed: 503 dependency_unavailable.

ETag / If-Match will protect mutable resources from two writers silently overwriting each other (for example, a human and an agent editing the same appointment):

1. GET a mutable resource — the response carries an ETag header (creates and updates return the fresh ETag too).
2. Send PATCH or DELETE with If-Match: <etag>.
3. On success the response carries the new ETag. If the resource changed in between, the call fails with 412 stale_version — re-read, reapply your change, retry. A missing If-Match where it is required fails with 428 precondition_required.

PII & redaction

Client contact fields — phone, email, additional_phone — are sensitive:

• Reading them requires the clients:read_contact scope and the corresponding business permission of the token subject.
• When access is refused, a contact field is returned as null and its name is listed in redacted_fields of the same object. It is never replaced with a mask, a placeholder or an empty string, so an integration cannot write a redacted value back.
• expand[]=client follows the same rule: expanding a client on an appointment or visit without contact access returns the client with redacted contact fields. Expansion never widens access.
• 422 phone_taken on create/update is part of clients:write (no extra clients:read_contact). It only signals that the phone is already owned by another client of this Location — it does not return that client's identity or contact payload. Phone-bearing writes are audited and share an anti-enumeration rate limit with exact contact search so the existence signal cannot be bulk-probed.

HTTP negotiation and caching

Clients should send Accept: application/json for successful resource responses and application/problem+json for errors; unsupported response media types fail with 406 not_acceptable. JSON is UTF-8; Content-Type may include charset=utf-8. Read operations may include Cache-Control appropriate to the resource (no-store for PII-bearing reads, short private or public max-age for dictionaries and metadata). ETag and If-Match are planned (see Idempotency & concurrency); when they ship, mutable resource reads return strong ETags and If-Match: * is not accepted on PATCH/DELETE — clients re-read and send the concrete strong ETag.