GroundIT API

1 · Start here

2 · Authentication — the product app API

Every /api/v1/* operation is authenticated by an opaque session cookie. No token, refresh token, or Keycloak material is ever returned to a client: the cookie is the credential, and it is HttpOnly.

• Sign in — POST /api/v1/auth/login with { email, password, market, workspace? }. GroundIT owns no password; it presents the credential to the market's Keycloak realm and, on success, mints a product session and sets the cookie. A market with no configured client secret is sealed and always answers 401.
• Arrive from the One portal — POST /api/sso/exchange verifies the platform's Ed25519 bridge token and mints the same product session (see §5).
• Who am I — GET /api/v1/auth/session returns the principal and its resolved grants. It requires a session but no permission token, so any signed-in principal can ask.
• Sign out — POST /api/v1/auth/logout revokes the session and clears the cookie (always, even for an unknown handle).

Authorization is re-resolved server-side on every request. The session carries identity only; permissions come from the tenant's RBAC state, so a client must never cache or infer an allow decision. Each operation's operationId is its permission token (<module>.<resource>.<action>, ADR 0015) — that string is the single join key between this API, the RBAC catalogue, and the traceability corpus.

Tenancy is never a parameter. tenant_id never appears in a path, query, or body on the product surface: it comes from the session and is enforced in Postgres by row-level security.

3 · Errors — RFC 9457 problem+json

Every error response is application/problem+json and carries a stable machine-readable code alongside the HTTP status. Branch on code, never on detail (human text, may change) or on the status alone. Every response — success or error — also carries X-Correlation-Id; log it, and quote it when raising an issue.

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "code": "TOKEN_DENIED",
  "detail": "human-readable, non-contractual",
  "instance": "/api/v1/employees/…",
  "correlation_id": "…"
}

The codes below are read from the running build's catalogue, so this list cannot drift from what this deployment actually emits:

The entitlement family is ordered subscription-status → feature-flag → numeric-limit and surfaces as 423 TENANT_PAST_DUE (writes blocked, reads still fine) · 402 FEATURE_NOT_IN_PLAN · 402 PLAN_LIMIT_EXCEEDED · 403 TENANT_SUSPENDED · 410 TENANT_CANCELLED. A row hidden by row-level security answers 404 NOT_FOUND, deliberately indistinguishable from an absent row.

4 · Pagination, idempotency, concurrency

• Pagination is cursor-based. Send page[size] with page[after] / page[before]; read the next cursor out of the response envelope. Offsets are not supported — do not synthesise them.
• Every mutation is idempotent. Send an Idempotency-Key (a UUID you generate per logical attempt) on POST/PATCH/DELETE and reuse it verbatim on retry. A replay returns the original result with Idempotency-Replayed: true; the same key with a different body is rejected 409 IDEMPOTENCY_KEY_REUSE. This is what makes the mobile offline queue safe.
• "Same body" is a deep compare, not a byte compare. JSON object key order never matters — at any depth — so you do not have to serialise a retry the same way you serialised the first attempt. What does matter: array order and length (a reordered batch is a different request), an explicit null (which is not the same as omitting the field), and value types (1 is not "1").
• Updates are version-checked. Reads of mutable entities return an ETag; send it back as If-Match. A missing header is 428 PRECONDITION_REQUIRED, a stale one 412 VERSION_CONFLICT.
• Localization — send Accept-Language (en · ar). Arabic responses are RTL and may carry Hijri (Umm al-Qura) date companions; money is always a decimal string plus an ISO-4217 currency, never a float.

5 · Platform inbound (/platform/*) and the SSO exchange

These two channels are the Sysmedac One seam. Both sit outside the /api/v1 prefix, because the caller signs (or links to) the exact wire path.

Signing an inbound /platform/* call

Every call except GET /platform/health carries three signals; any failure is a single opaque 401 that tells you nothing about which one failed.

Authorization:            Bearer <service-token plaintext>
X-Platform-Signature:     <hex lowercase HMAC-SHA256>      (X-SaasPortal-Signature also accepted)
X-Platform-Timestamp:     <epoch MILLISECONDS>             (X-SaasPortal-Timestamp also accepted)
Idempotency-Key:          <uuid>   (required on every mutation; X-Idempotency-Key also accepted)

signature = HMAC-SHA256(
    key     = <the same service-token plaintext>,
    message = timestamp + "\n" + METHOD + "\n" + path + "\n" + sha256hex(body)
)

• path is the full request target including the query string — sign what you put on the wire.
• An absent or empty body hashes as sha256(""), not as the empty string.
• timestamp is epoch milliseconds and must fall inside the replay window (default ±300 s).
• The service token is stored only as a bcrypt hash; a previous hash stays valid through a 7-day rotation overlap.
• This surface writes TenantCache and is therefore not entitlement gated — it never answers 402/403/410/423.

Bridge-token SSO

POST /api/sso/exchange takes the platform's Ed25519-signed bridge token and mints a GroundIT product session (the same cookie as §2). GroundIT is a verifier only — it holds the platform's public key and never a portal credential. aud is always enforced, iss when configured, and the channel is sealed (every exchange 401) until the public key is provisioned. Full request/response shapes are in Platform inbound + SSO.

6 · Product app API — /api/v1

One document per module grouping. Audience: Flutter mobile and Sysmedac One portal / web back-office.

7 · Platform inbound + SSO

8 · Fintech ports

9 · Public legal content

9 · How current is this?

These documents are the spec of record from planning/api-docs/openapi/, served straight off this deployment's build — not a snapshot pasted into a wiki. The repository's working contract makes them release-blocking: every change to an endpoint, DTO, error code, header, or auth requirement updates the owning OpenAPI document in the same change, and an automated check fails the build when a route the API actually serves is absent from a served document.

The spec deliberately runs ahead of the implementation — it is the full designed surface, and endpoints keep landing sprint by sprint. If an operation you need answers 404, it is specced but not yet built; ask before designing around it.