{ "openapi": "3.1.0", "info": { "title": "GSB e-Services federation API", "version": "1.1.0", "description": "Contract v1 between the national hub and the MDA nodes (backlog FED-02). Every request and answer is signed (detached JWS, ES256 - docs/federation/README.md \"Message signing\"); transport is mTLS. Bodies are canonical JSON validated against the JSON Schemas in schemas/ (unknown fields are refused). Writes need an Idempotency-Key; a repeat with the same key returns the first answer. Versioned under /fed/v1; a sunset is announced with the Deprecation and Sunset headers. Revision 2 (1.1.0, FED-03): catalogue.put answers catalogue-ack.json; catalogue.list takes full, ids and limit; the service manifest gains its signature, the passport detail and tombstones (schemas/service-manifest.json $comment) - additive, hubs first." }, "servers": [ { "url": "https://fed.{instance}.gsb.gov.zm", "variables": { "instance": { "default": "hub", "description": "The instance's federation host (ingress with mTLS)." } } } ], "security": [ { "federationSignature": [] } ], "paths": { "/fed/v1/ping": { "post": { "operationId": "ping", "summary": "Signed liveness and trust check between two instances", "x-gsb-scope": "ping", "x-gsb-idempotent-write": true, "x-gsb-built-by": "FED-01/FED-02 (wave 1, lane F1)", "security": [ { "federationSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/FederationId" }, { "$ref": "#/components/parameters/TraceParent" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "schemas/ping-request.json" } } } }, "responses": { "200": { "description": "Signed answer (X-GSB-Fed-Signature).", "headers": { "X-GSB-Fed-Signature": { "$ref": "#/components/headers/ResponseSignature" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "schemas/ping-response.json" } } } }, "400": { "description": "FED_INVALID (unknown field, wrong type - `errors` lists the fields), FED_IDEMPOTENCY_KEY_REQUIRED, FED_HEADER_MISMATCH, FED_VERSION", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "401": { "description": "FED_UNSIGNED, FED_MALFORMED, FED_UNKNOWN_ISSUER, FED_UNKNOWN_KEY, FED_BAD_SIGNATURE, FED_WRONG_AUDIENCE, FED_EXPIRED, FED_NOT_YET_VALID, FED_WRONG_TARGET, FED_REPLAY, FED_MTLS_REQUIRED, FED_MTLS_MISMATCH", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "403": { "description": "FED_SCOPE: the calling peer does not hold this operation's scope", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "409": { "description": "IDEMPOTENCY_IN_PROGRESS: the first request with this key is still running (Retry-After)", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "422": { "description": "IDEMPOTENCY_KEY_REUSED: the key was used with another body", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "429": { "description": "Too many requests from this address (FED_RATE_LIMIT_PER_MIN)", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "501": { "description": "FED_NOT_IMPLEMENTED: part of contract v1, not offered by this instance yet", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } } } } }, "/fed/v1/catalogue/services/{serviceId}": { "put": { "operationId": "catalogue.put", "summary": "A node pushes a signed service manifest (publish, unpublish, withdraw)", "x-gsb-scope": "catalogue:write", "x-gsb-idempotent-write": true, "x-gsb-built-by": "FED-03", "security": [ { "federationSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/FederationId" }, { "$ref": "#/components/parameters/TraceParent" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "schemas/service-manifest.json" } } } }, "responses": { "200": { "description": "Signed answer (X-GSB-Fed-Signature): applied, or unchanged when the hub already mirrors exactly this version.", "headers": { "X-GSB-Fed-Signature": { "$ref": "#/components/headers/ResponseSignature" } }, "content": { "application/json": { "schema": { "$ref": "schemas/catalogue-ack.json" } } } }, "400": { "description": "FED_INVALID (unknown field, wrong type - `errors` lists the fields), FED_IDEMPOTENCY_KEY_REQUIRED, FED_HEADER_MISMATCH, FED_VERSION, FED_PATH_MISMATCH (the path's serviceId is not the manifest's), FED_HASH_MISMATCH (contentHash does not match the content)", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "401": { "description": "FED_UNSIGNED, FED_MALFORMED, FED_UNKNOWN_ISSUER, FED_UNKNOWN_KEY, FED_BAD_SIGNATURE, FED_WRONG_AUDIENCE, FED_EXPIRED, FED_NOT_YET_VALID, FED_WRONG_TARGET, FED_REPLAY, FED_MTLS_REQUIRED, FED_MTLS_MISMATCH, FED_MANIFEST_UNSIGNED / FED_MANIFEST_SIGNATURE (the manifest's own signature is missing, not the sender's or does not verify)", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "403": { "description": "FED_SCOPE: the calling peer does not hold this operation's scope; FED_NOT_OWNER: the manifest names another owner node, or a ministry the node does not serve, or a service another node owns", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "409": { "description": "IDEMPOTENCY_IN_PROGRESS: the first request with this key is still running (Retry-After); FED_STALE_VERSION: the hub mirrors a newer version; FED_VERSION_CONFLICT: the hub mirrors this version with other content; FED_SERVICE_ID_LOCAL: the hub hosts a service with this id itself", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "422": { "description": "IDEMPOTENCY_KEY_REUSED: the key was used with another body", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "429": { "description": "Too many requests from this address (FED_RATE_LIMIT_PER_MIN)", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "501": { "description": "FED_NOT_IMPLEMENTED: part of contract v1, not offered by this instance yet", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } } }, "description": "The node pushes the manifest of a service it owns whenever its catalogue entry changes (publish, edit, unpublish, withdraw). The hub checks the request signature, then the manifest: its owner is the calling node (and, when the registry lists the node's ministries, the manifest's ministry is one of them), its contentHash matches, its own signature (`signature`, typ gsb-manifest+jws) verifies against the node's keys, and its version is not older than the mirrored one. The apply is idempotent on (serviceId, version, contentHash)." } }, "/fed/v1/catalogue": { "get": { "operationId": "catalogue.list", "summary": "The hub pulls catalogue changes since a cursor (heals missed pushes)", "x-gsb-scope": "catalogue:read", "x-gsb-idempotent-write": false, "x-gsb-built-by": "FED-03", "security": [ { "federationSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/FederationId" }, { "$ref": "#/components/parameters/TraceParent" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "The cursor of the previous page (pull reconciliation)." }, { "name": "full", "in": "query", "required": false, "schema": { "enum": [ "0", "1" ] }, "description": "1: include each item's signed manifest (manifestJws)." }, { "name": "ids", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3800 }, "description": "Comma-separated service ids (at most 100): just these entries, whatever their change time." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,3}$" }, "description": "Items per page (1-500, default 100; 25 with full=1)." } ], "responses": { "200": { "description": "Signed answer (X-GSB-Fed-Signature).", "headers": { "X-GSB-Fed-Signature": { "$ref": "#/components/headers/ResponseSignature" } }, "content": { "application/json": { "schema": { "$ref": "schemas/catalogue-page.json" } } } }, "400": { "description": "FED_INVALID (unknown field, wrong type - `errors` lists the fields), FED_IDEMPOTENCY_KEY_REQUIRED, FED_HEADER_MISMATCH, FED_VERSION", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "401": { "description": "FED_UNSIGNED, FED_MALFORMED, FED_UNKNOWN_ISSUER, FED_UNKNOWN_KEY, FED_BAD_SIGNATURE, FED_WRONG_AUDIENCE, FED_EXPIRED, FED_NOT_YET_VALID, FED_WRONG_TARGET, FED_REPLAY, FED_MTLS_REQUIRED, FED_MTLS_MISMATCH", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "403": { "description": "FED_SCOPE: the calling peer does not hold this operation's scope", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "429": { "description": "Too many requests from this address (FED_RATE_LIMIT_PER_MIN)", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "501": { "description": "FED_NOT_IMPLEMENTED: part of contract v1, not offered by this instance yet", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } } }, "description": "Pull reconciliation (FED-03): the hub reads the node's catalogue ledger - every service the node has offered nationally, with its catalogue version, content hash and state - ordered by change time. With `since` only entries changed after that cursor; with `full=1` each item carries its signed manifest (`manifestJws`, attached compact JWS); with `ids` just those services. The node refreshes its ledger from its live services first, so drift made outside the publishing flow is found too. Answers are signed." } }, "/fed/v1/submissions": { "post": { "operationId": "submissions.create", "summary": "The hub relays a citizen application to the owner node", "x-gsb-scope": "submissions:write", "x-gsb-idempotent-write": true, "x-gsb-built-by": "FED-05", "security": [ { "federationSignature": [] } ], "parameters": [ { "$ref": "#/components/parameters/FederationId" }, { "$ref": "#/components/parameters/TraceParent" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/CitizenAssertion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "schemas/submission-request.json" } } } }, "responses": { "200": { "description": "Signed answer (X-GSB-Fed-Signature): the node made the case - 201 when made now, 200 with `replayed` when this hub submission had already made it (a repeat after a lost answer: one case).", "headers": { "X-GSB-Fed-Signature": { "$ref": "#/components/headers/ResponseSignature" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "schemas/submission-ack.json" } } } }, "201": { "description": "Signed answer: the node made the case (FED-05).", "headers": { "X-GSB-Fed-Signature": { "$ref": "#/components/headers/ResponseSignature" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "schemas/submission-ack.json" } } } }, "400": { "description": "FED_INVALID (unknown field, wrong type - `errors` lists the fields), FED_IDEMPOTENCY_KEY_REQUIRED, FED_HEADER_MISMATCH, FED_VERSION", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "401": { "description": "FED_UNSIGNED, FED_MALFORMED, FED_UNKNOWN_ISSUER, FED_UNKNOWN_KEY, FED_BAD_SIGNATURE, FED_WRONG_AUDIENCE, FED_EXPIRED, FED_NOT_YET_VALID, FED_WRONG_TARGET, FED_REPLAY, FED_MTLS_REQUIRED, FED_MTLS_MISMATCH", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "403": { "description": "FED_SCOPE: the calling peer does not hold this operation's scope; the citizen assertion refused: FED_ASSURANCE_TOO_LOW, FED_PRINCIPAL_NOT_APPLICANT, FED_PRINCIPAL_INACTIVE", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "404": { "description": "FED_SERVICE_UNKNOWN: not an active service of this node", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "409": { "description": "IDEMPOTENCY_IN_PROGRESS: the first request with this key is still running (Retry-After); DUPLICATE_APPLICATION (EF-49), FED_SERVICE_CLOSED (intake window): the citizen must act", "content": { "application/json": { "schema": { "$ref": "schemas/error.json" } } } }, "422": { "description": "IDEMPOTENCY_KEY_REUSED: the key was used with another body; FED_VALIDATION / FED_FORM_CHANGED (the node's live form - `errors` per field; FED_FORM_CHANGED when the form changed since the hub's version), FED_FILE_REFUSED / FED_FILE_CHECKSUM (a file: type, size, antivirus, or not the bytes announced - `errors` with `document: