{ "openapi": "3.1.0", "info": { "title": "Gridex Staff API", "version": "2026-10-12.1", "description": "Staff accounts and customer service from your own backend. Every staff call requires an API credential and a signed proof of the acting staff login. The platform derives the organization and permissions from those two identities. Every response carries a server-issued X-Request-ID equal to request_id in the body. The optional x-gridex-expected-project-ref header pins the storage project (412 storage_project_mismatch otherwise), and list endpoints accept the opt-in x-gridex-query-parsing: strict profile. Central account state and current identity bindings authorize normal signed requests. Local Auth sessions are verified at identity resolution, invitation acceptance and by the portal backend before signing." }, "servers": [ { "url": "https://app.gridex.se" } ], "x-contract-schema-version": "2026-10-09.1", "x-gridex-release-version": "2026-10-12.1", "paths": { "/api/v1/staff/users": { "get": { "operationId": "getApiV1StaffUsers", "summary": "List staff accounts with their membership status", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "maximum": 1000000 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled", "removed", "invited", "pending", "suspended", "removed_from_company", "invitation_revoked", "locked_security", "revoked" ] } }, { "$ref": "#/components/parameters/ExpectedProjectRef" }, { "$ref": "#/components/parameters/QueryParsing" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffUsersResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_users.read" ], "x-required-permission": "users.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "List staff accounts with their membership status." }, "post": { "operationId": "postApiV1StaffUsers", "summary": "Invite staff to the organization within the acting staff role ceiling", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffUsersResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_users.write" ], "x-required-permission": "users.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffInviteRequest" } } } }, "description": "Invite staff to the organization within the acting staff role ceiling." } }, "/api/v1/staff/users/{id}": { "patch": { "operationId": "patchApiV1StaffUsersId", "summary": "Change a staff role while preserving the final active administrator", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchApiV1StaffUsersIdResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_users.write" ], "x-required-permission": "users.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffRoleChangeRequest" } } } }, "description": "Change a staff role while preserving the final active administrator." } }, "/api/v1/staff/users/{id}/disable": { "post": { "operationId": "postApiV1StaffUsersIdDisable", "summary": "Disable staff while preventing self disable and loss of the final administrator", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffUsersIdDisableResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_users.write" ], "x-required-permission": "users.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffDisableRequest" } } } }, "description": "Disable staff while preventing self disable and loss of the final administrator." } }, "/api/v1/staff/users/{id}/enable": { "post": { "operationId": "postApiV1StaffUsersIdEnable", "summary": "Reactivate a disabled staff membership", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffUsersIdEnableResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_users.write" ], "x-required-permission": "users.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "Reactivate a disabled staff membership.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffEnableRequest" } } } } } }, "/api/v1/staff/roles": { "get": { "operationId": "getApiV1StaffRoles", "summary": "List staff roles and whether the acting staff can assign each role", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffRolesResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_users.read" ], "x-required-permission": "users.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "List staff roles and whether the acting staff can assign each role." } }, "/api/v1/staff/customers": { "get": { "operationId": "getApiV1StaffCustomers", "summary": "Search and page customers belonging to the authenticated organization", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "maximum": 1000000 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "draft", "pending_verification", "active", "inactive", "moved", "terminated", "blocked", "archived" ] } }, { "name": "customer_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "private", "business", "association" ] } }, { "$ref": "#/components/parameters/ExpectedProjectRef" }, { "$ref": "#/components/parameters/QueryParsing" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffCustomersResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_customers.read" ], "x-required-permission": "customers.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "Search and page customers belonging to the authenticated organization." } }, "/api/v1/staff/customers/{ref}": { "get": { "operationId": "getApiV1StaffCustomersRef", "summary": "Retrieve a customer with masked identity numbers and explicit public fields", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffCustomersRefResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_customers.read" ], "x-required-permission": "customers.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "Retrieve a customer with masked identity numbers and explicit public fields." } }, "/api/v1/staff/customers/{ref}/contact": { "patch": { "operationId": "patchApiV1StaffCustomersRefContact", "summary": "Update customer contact fields using an expected version", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchApiV1StaffCustomersRefContactResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_customers.write" ], "x-required-permission": "masterdata.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffContactChangeRequest" } } } }, "description": "Update customer contact fields using an expected version." } }, "/api/v1/staff/customers/{ref}/identity-change": { "post": { "operationId": "postApiV1StaffCustomersRefIdentityChange", "summary": "Request a customer identity change with customer approval when required", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffCustomersRefIdentityChangeResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_customers.write" ], "x-required-permission": "customers.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffIdentityChangeRequest" } } } }, "description": "Request a customer identity change with customer approval when required." } }, "/api/v1/staff/cases": { "get": { "operationId": "getApiV1StaffCases", "summary": "List customer cases available to staff in the authenticated organization", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "action_required", "awaiting_external_response", "billing_blocked", "manual_follow_up", "resolved", "cancelled", "closed" ] } }, { "name": "customer_reference", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 180 } }, { "$ref": "#/components/parameters/ExpectedProjectRef" }, { "$ref": "#/components/parameters/QueryParsing" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffCasesResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.read" ], "x-required-permission": "cases.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "List customer cases available to staff in the authenticated organization." }, "post": { "operationId": "postApiV1StaffCases", "summary": "Create a customer support case as the acting staff", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffCasesResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCaseCreateRequest" } } } }, "description": "Create a customer support case as the acting staff." } }, "/api/v1/staff/cases/{reference}": { "get": { "operationId": "getApiV1StaffCasesReference", "summary": "Retrieve a customer case including staff visible events and attachments", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffCasesReferenceResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.read" ], "x-required-permission": "cases.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "Retrieve a customer case including staff visible events and attachments." } }, "/api/v1/staff/cases/{reference}/messages": { "post": { "operationId": "postApiV1StaffCasesReferenceMessages", "summary": "Reply to a customer through the existing support conversation", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffCasesReferenceMessagesResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMessageRequest" } } } }, "description": "Reply to a customer through the existing support conversation." } }, "/api/v1/staff/cases/{reference}/notes": { "post": { "operationId": "postApiV1StaffCasesReferenceNotes", "summary": "Add an internal staff note to a customer case", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffCasesReferenceNotesResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffNoteRequest" } } } }, "description": "Add an internal staff note to a customer case." } }, "/api/v1/staff/cases/{reference}/phone-interactions": { "post": { "operationId": "postApiV1StaffCasesReferencePhoneInteractions", "summary": "Record a phone interaction and its customer verification evidence", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffCasesReferencePhoneInteractionsResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffPhoneRequest" } } } }, "description": "Record a phone interaction and its customer verification evidence." } }, "/api/v1/staff/cases/{reference}/status": { "patch": { "operationId": "patchApiV1StaffCasesReferenceStatus", "summary": "Change the status of a customer case", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchApiV1StaffCasesReferenceStatusResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffStatusRequest" } } } }, "description": "Change the status of a customer case." } }, "/api/v1/staff/cases/{reference}/assignee": { "patch": { "operationId": "patchApiV1StaffCasesReferenceAssignee", "summary": "Assign a customer case to active staff in the same organization", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchApiV1StaffCasesReferenceAssigneeResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffAssigneeRequest" } } } }, "description": "Assign a customer case to active staff in the same organization." } }, "/api/v1/staff/cases/{reference}/attachments": { "get": { "operationId": "getApiV1StaffCasesReferenceAttachments", "summary": "List staff visible attachments of a customer case", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation cursor returned as page.next_cursor; bound to this organization, customer and case." }, { "$ref": "#/components/parameters/ExpectedProjectRef" }, { "$ref": "#/components/parameters/QueryParsing" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffCasesReferenceAttachmentsResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.read" ], "x-required-permission": "cases.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "List staff visible attachments of a customer case." }, "post": { "operationId": "postApiV1StaffCasesReferenceAttachments", "summary": "Upload a staff attachment for content inspection before release", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "x-file-name", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "x-attachment-visibility", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "internal", "customer" ] } }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "201": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the stored result of an earlier identical request (same Idempotency-Key and body) is returned; false for a new execution. Current authentication, scopes, permission and active membership are checked before any stored result is replayed." }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postApiV1StaffCasesReferenceAttachmentsResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Attachment body exceeds 4 MiB.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Unsupported attachment content type.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.write" ], "x-required-permission": "cases.write", "x-scope-mode": "all", "x-idempotency-required": true, "x-rate-limit-class": "write", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "requestBody": { "required": true, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "maxLength": 4194304 } }, "image/png": { "schema": { "type": "string", "format": "binary", "maxLength": 4194304 } }, "image/jpeg": { "schema": { "type": "string", "format": "binary", "maxLength": 4194304 } } } }, "description": "Upload a staff attachment for content inspection before release." } }, "/api/v1/staff/cases/{reference}/attachments/{attachmentReference}/file": { "get": { "operationId": "getApiV1StaffCasesReferenceAttachmentsAttachmentReferenceFile", "summary": "Download a released staff visible attachment with its hash verified", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "name": "attachmentReference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "$ref": "#/components/parameters/ExpectedProjectRef" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.read" ], "x-required-permission": "cases.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "Download a released staff visible attachment with its hash verified." } }, "/api/v1/openapi/release-manifest.json": { "get": { "operationId": "getApiV1OpenapiReleaseManifestJson", "summary": "Machine-readable release manifest containing versions and SHA-256 digests for the public OpenAPI contracts", "x-required-scopes": [], "responses": { "200": { "description": "Aktuell kontraktsrelease.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReleaseManifest" } } }, "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } } }, "304": { "description": "Not Modified. The supplied If-None-Match value matches the current ETag.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } } } }, "security": [], "x-scope-mode": "all", "x-rate-limit-class": "read", "x-idempotency-required": false, "x-cache-policy": "private-revalidate", "x-public-id-policy": "none", "description": "Machine-readable release manifest containing versions and SHA-256 digests for the public OpenAPI contracts." } }, "/api/v1/openapi/staff-v1.json": { "get": { "summary": "Current OpenAPI specification for staff integrations", "description": "Current OpenAPI specification for staff integrations.", "security": [], "responses": { "200": { "description": "Versionerad OpenAPI JSON", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-12.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified. The supplied If-None-Match value matches the current ETag.", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-12.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } } } }, "x-required-scopes": [], "operationId": "getApiV1OpenapiStaffV1Json", "x-scope-mode": "all", "x-rate-limit-class": "read", "x-idempotency-required": false, "x-cache-policy": "private-revalidate", "x-public-id-policy": "none" } }, "/api/v1/openapi/2026-10-04.1/staff-v1.json": { "get": { "summary": "Immutable Staff OpenAPI release 2026-10-04", "description": "Immutable Staff OpenAPI release 2026-10-04.1.", "security": [], "responses": { "200": { "description": "Versionerad OpenAPI JSON", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-04.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified. The supplied If-None-Match value matches the current ETag.", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-04.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } } } }, "x-required-scopes": [], "operationId": "getApiV1Openapi202610041StaffV1Json", "x-scope-mode": "all", "x-rate-limit-class": "read", "x-idempotency-required": false, "x-cache-policy": "public-immutable", "x-public-id-policy": "none" } }, "/api/v1/staff/cases/{reference}/events": { "get": { "operationId": "getApiV1StaffCasesReferenceEvents", "summary": "List staff visible case events with a case bound continuation cursor", "security": [ { "bearerAuth": [], "staffAssertion": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "x-gridex-staff-assertion", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation cursor returned as page.next_cursor; bound to this organization, customer and case." }, { "$ref": "#/components/parameters/ExpectedProjectRef" }, { "$ref": "#/components/parameters/QueryParsing" } ], "responses": { "200": { "description": "Successful staff operation.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getApiV1StaffCasesReferenceEventsResponse" } } } }, "400": { "description": "Malformed request or missing Idempotency-Key.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "API credential or staff assertion missing or invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Insufficient API scope, staff permission or active organization membership.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The resource does not exist in this organization.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Version, membership, role safeguard or idempotency conflict.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/OrganizationGone" }, "412": { "description": "storage_project_mismatch: x-gridex-expected-project-ref is malformed or names another storage project. Nothing was executed; call the deployment that serves the expected project.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request fields or business rules are invalid.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "$ref": "#/components/responses/OrganizationPaused" }, "429": { "description": "API traffic limit exceeded.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal processing failure without private implementation details.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required service unavailable; retry only when the error is retryable.", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Gridex-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "X-Gridex-Project-Ref": { "$ref": "#/components/headers/ProjectRef" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scopes": [ "staff_cases.read" ], "x-required-permission": "cases.read", "x-scope-mode": "all", "x-idempotency-required": false, "x-rate-limit-class": "read", "x-cache-policy": "no-store", "x-public-id-policy": "staff-identities-and-opaque-references", "description": "List staff visible case events with a case bound continuation cursor." } }, "/api/v1/openapi/2026-10-09.1/staff-v1.json": { "get": { "summary": "Immutable Staff OpenAPI release 2026-10-04", "description": "Immutable Staff OpenAPI release 2026-10-09.1.", "security": [], "responses": { "200": { "description": "Versionerad OpenAPI JSON", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-09.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified. The supplied If-None-Match value matches the current ETag.", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-09.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } } } }, "x-required-scopes": [], "operationId": "getApiV1Openapi202610091StaffV1Json", "x-scope-mode": "all", "x-rate-limit-class": "read", "x-idempotency-required": false, "x-cache-policy": "public-immutable", "x-public-id-policy": "none" } }, "/api/v1/openapi/2026-10-12.1/staff-v1.json": { "get": { "summary": "Immutable Staff OpenAPI release 2026-10-04", "description": "Immutable Staff OpenAPI release 2026-10-12.1.", "security": [], "responses": { "200": { "description": "Versionerad OpenAPI JSON", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-12.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified. The supplied If-None-Match value matches the current ETag.", "headers": { "X-Gridex-Contract-Version": { "description": "Revision of the OpenAPI document being fetched; business responses use x-contract-schema-version.", "schema": { "type": "string", "const": "2026-10-12.1" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Content-Type": { "$ref": "#/components/headers/ContentType" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" } } } }, "x-required-scopes": [], "operationId": "getApiV1Openapi202610121StaffV1Json", "x-scope-mode": "all", "x-rate-limit-class": "read", "x-idempotency-required": false, "x-cache-policy": "public-immutable", "x-public-id-policy": "none" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Server-side Gridex API credential with the required staff scope." }, "staffAssertion": { "type": "apiKey", "in": "header", "name": "x-gridex-staff-assertion", "description": "Compact JWT signed by your backend with RS256, PS256 or ES256. iss/aud must equal the configured staff identity provider. sub identifies the central OPS staff actor. iat/exp define a lifetime of at most 900 seconds; jti is unique and accepted only once. Each request checks the central account state, company membership and server-calculated permissions. Independent tenant Auth identities also require the current registered local-to-central binding ID/version and verified local identity claims. Tenant Auth getUser verifies the login during identity resolution, invitation acceptance and backend session verification; normal Staff API calls validate the already signed proof and current central binding without calling tenant Auth getUser again." } }, "parameters": { "RequestId": { "name": "x-request-id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional client correlation value (1-128 characters of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\"). It is recorded separately for support as the client correlation id and never replaces the server request id." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9._:+~-]+$" }, "description": "Reuse the same key and unchanged body for a retry. Sign a fresh assertion with a new jti for every attempt." }, "ExpectedProjectRef": { "name": "x-gridex-expected-project-ref", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9]{20}$" }, "description": "Optional 20-character storage project reference you expect to serve this call. A malformed value, or a value that differs from the project served by this deployment, returns 412 storage_project_mismatch before authentication, rate limiting, audit or any write; nothing is executed." }, "QueryParsing": { "name": "x-gridex-query-parsing", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "compatible", "strict" ], "default": "compatible" }, "description": "List query parsing profile. compatible (default) keeps the parsing each endpoint has always accepted. strict applies one rule to every Staff list endpoint: each query parameter at most once, and page, page_size and limit only as plain decimal digits without sign, whitespace, exponent, fraction, hexadecimal prefix or leading zero. Violations, and unknown profile values, return 422 invalid_field with error.field naming the parameter, before any data is read." } }, "headers": { "GridexContractVersion": { "description": "Canonical contract version used for this response.", "schema": { "type": "string", "const": "2026-10-09.1" } }, "RequestId": { "description": "Server-issued request id for this call. The same value is returned as request_id in the body (including errors) and recorded in the request log. A client-supplied x-request-id is never echoed here.", "schema": { "type": "string" } }, "RateLimitLimit": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "schema": { "type": "string", "format": "date-time" } }, "RetryAfter": { "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "description": "Strong entity tag for conditional retrieval.", "schema": { "type": "string" } }, "CacheControl": { "description": "Caching policy for this document.", "schema": { "type": "string" } }, "ContentType": { "description": "Response media type.", "schema": { "type": "string" } }, "ContentDisposition": { "description": "Suggested inline filename.", "schema": { "type": "string" } }, "Vary": { "description": "Request headers that affect cache validation.", "schema": { "type": "string" } }, "ProjectRef": { "description": "Storage project reference that served this call. Present when the deployment serves an identified project; compare it with x-gridex-expected-project-ref.", "schema": { "type": "string", "pattern": "^[a-z0-9]{20}$" } }, "GridexDocumentationVersion": { "description": "Optional documentation revision associated with this business response. It does not change contract_schema_version or the supported wire schema.", "schema": { "type": "string", "const": "2026-10-12.1" } } }, "schemas": { "OpenApiReleaseManifest": { "type": "object", "additionalProperties": false, "required": [ "release_version", "website_openapi_version", "customer_portal_openapi_version", "staff_openapi_version", "runtime_contract_version", "guide_version", "released_at", "generated_at", "build_commit", "compatibility_classification", "deprecated_features", "minimum_tenant_integration_version", "specifications" ], "properties": { "release_version": { "type": "string", "const": "2026-10-12.1" }, "website_openapi_version": { "type": "string", "const": "2026-10-12.1" }, "customer_portal_openapi_version": { "type": "string", "const": "2026-10-12.1" }, "staff_openapi_version": { "type": "string", "const": "2026-10-12.1" }, "runtime_contract_version": { "type": "string", "const": "2026-10-09.1" }, "guide_version": { "type": "string", "const": "2026-10-12.1" }, "released_at": { "type": "string", "format": "date-time" }, "generated_at": { "type": "string", "format": "date-time" }, "build_commit": { "type": "string" }, "compatibility_classification": { "type": "string", "enum": [ "backward-compatible", "breaking-client-update-required", "breaking" ] }, "deprecated_features": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "feature", "replacement", "sunset_at" ], "properties": { "feature": { "type": "string" }, "replacement": { "type": "string" }, "sunset_at": { "type": "string", "format": "date-time" } } } }, "minimum_tenant_integration_version": { "type": "string", "const": "2026-10-02.3" }, "specifications": { "type": "object", "additionalProperties": false, "required": [ "website", "customer_portal", "staff" ], "properties": { "website": { "$ref": "#/components/schemas/OpenApiReleaseSpecification" }, "customer_portal": { "$ref": "#/components/schemas/OpenApiReleaseSpecification" }, "staff": { "$ref": "#/components/schemas/OpenApiReleaseSpecification" } } } } }, "OpenApiReleaseSpecification": { "type": "object", "additionalProperties": false, "required": [ "contract_name", "contract_version", "url", "immutable_url", "sha256", "compatibility" ], "properties": { "contract_name": { "type": "string" }, "contract_version": { "type": "string", "const": "2026-10-12.1" }, "url": { "type": "string", "format": "uri" }, "immutable_url": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "compatibility": { "type": "string", "enum": [ "backward-compatible", "breaking-client-update-required", "breaking" ] } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "error", "request_id", "correlation_id", "contract_schema_version" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "retryable", "field", "blockers" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "stage": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "hint": { "type": "string" }, "retryable": { "type": "boolean" }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/ApiBlocker" } }, "details": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } }, "request_id": { "type": "string" }, "correlation_id": { "type": "string" }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } }, "description": "Canonical error envelope. Business and provider failures use one nested error object; no parallel top-level aliases are emitted." }, "ApiBlocker": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "resource_type": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "count": { "type": [ "integer", "null" ] }, "recommended_action": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "StaffAccount": { "type": "object", "additionalProperties": false, "required": [ "user_id", "email", "full_name", "role_key", "membership_role", "status", "invited_at", "accepted_at", "disabled_at" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "role_key": { "type": "string" }, "membership_role": { "type": "string" }, "status": { "type": "string" }, "invited_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StaffAccountState": { "type": "object", "additionalProperties": false, "required": [ "user_id", "role_key", "membership_role", "status" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "role_key": { "type": "string" }, "membership_role": { "type": "string" }, "status": { "type": "string" } } }, "StaffInviteResult": { "type": "object", "additionalProperties": false, "required": [ "email", "role_key", "membership_role", "status" ], "properties": { "email": { "type": "string" }, "role_key": { "type": "string" }, "membership_role": { "type": "string" }, "status": { "type": "string", "const": "pending" } } }, "StaffRole": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "description", "permissions", "assignable" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "assignable": { "type": "boolean" } } }, "StaffInviteRequest": { "type": "object", "additionalProperties": false, "required": [ "email", "role_key" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "full_name": { "type": [ "string", "null" ], "maxLength": 200 }, "role_key": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "StaffRoleChangeRequest": { "type": "object", "additionalProperties": false, "required": [ "role_key" ], "properties": { "role_key": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "StaffDisableRequest": { "type": "object", "additionalProperties": false, "required": [], "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "StaffPagination": { "type": "object", "additionalProperties": false, "required": [ "page", "page_size", "total", "has_more" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" } } }, "StaffCustomerSummary": { "type": "object", "additionalProperties": false, "required": [ "customer_reference", "customer_number", "customer_type", "status", "display_name", "first_name", "last_name", "company_name", "email", "phone", "personal_number_masked", "org_number_masked", "created_at" ], "properties": { "customer_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "customer_number": { "type": [ "string", "null" ] }, "customer_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "personal_number_masked": { "type": [ "string", "null" ] }, "org_number_masked": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StaffCustomerContact": { "type": "object", "additionalProperties": false, "required": [ "contact_reference", "type", "name", "email", "phone", "title", "is_primary" ], "properties": { "contact_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" } } }, "StaffCustomerAddress": { "type": "object", "additionalProperties": false, "required": [ "address_reference", "type", "street_1", "street_2", "postal_code", "city", "country", "is_active" ], "properties": { "address_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "type": { "type": [ "string", "null" ] }, "street_1": { "type": [ "string", "null" ] }, "street_2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } } }, "StaffCustomerSite": { "type": "object", "additionalProperties": false, "required": [ "facility_reference", "site_name", "facility_id", "site_type", "status", "price_area_code", "street", "postal_code", "city" ], "properties": { "facility_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "site_name": { "type": [ "string", "null" ] }, "facility_id": { "type": [ "string", "null" ] }, "site_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "price_area_code": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } } }, "StaffCustomer": { "type": "object", "additionalProperties": false, "required": [ "customer_reference", "customer_number", "customer_type", "status", "display_name", "first_name", "last_name", "company_name", "email", "phone", "personal_number_masked", "org_number_masked", "created_at", "invoice_email", "preferred_language", "apartment_number", "updated_at", "contacts", "addresses", "sites", "contacts_page", "addresses_page", "sites_page" ], "properties": { "customer_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "customer_number": { "type": [ "string", "null" ] }, "customer_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "personal_number_masked": { "type": [ "string", "null" ] }, "org_number_masked": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "invoice_email": { "type": [ "string", "null" ] }, "preferred_language": { "type": [ "string", "null" ] }, "apartment_number": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCustomerContact" } }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCustomerAddress" } }, "sites": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCustomerSite" } }, "contacts_page": { "$ref": "#/components/schemas/StaffEmbeddedCollectionPage" }, "addresses_page": { "$ref": "#/components/schemas/StaffEmbeddedCollectionPage" }, "sites_page": { "$ref": "#/components/schemas/StaffEmbeddedCollectionPage" } } }, "StaffCustomerPagination": { "type": "object", "additionalProperties": false, "required": [ "page", "page_size", "total", "total_pages" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 } } }, "StaffContactChangeRequest": { "type": "object", "additionalProperties": false, "required": [ "expectedUpdatedAt" ], "properties": { "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "invoice_email": { "type": [ "string", "null" ], "maxLength": 320 }, "preferred_language": { "type": [ "string", "null" ], "maxLength": 20 }, "apartment_number": { "type": [ "string", "null" ], "maxLength": 20 } }, "anyOf": [ { "required": [ "email" ] }, { "required": [ "phone" ] }, { "required": [ "invoice_email" ] }, { "required": [ "preferred_language" ] }, { "required": [ "apartment_number" ] } ] }, "StaffContactChangeResult": { "type": "object", "additionalProperties": false, "required": [ "customer_reference", "changed", "customer_updated_at" ], "properties": { "customer_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "changed": { "type": "boolean" }, "customer_updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StaffIdentityChangeRequest": { "type": "object", "additionalProperties": false, "required": [ "field", "new_value", "reason" ], "properties": { "field": { "type": "string", "enum": [ "personal_number", "org_number" ] }, "new_value": { "type": "string", "minLength": 1, "maxLength": 32 }, "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "StaffIdentityChangeResult": { "type": "object", "additionalProperties": false, "required": [ "request_reference", "status", "recipient_masked", "expires_at", "contract_count", "takeover_required" ], "properties": { "request_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "status": { "type": "string", "enum": [ "applied", "pending_customer_approval" ] }, "recipient_masked": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "contract_count": { "type": [ "integer", "null" ], "minimum": 0 }, "takeover_required": { "type": [ "boolean", "null" ] } } }, "StaffCase": { "type": "object", "additionalProperties": false, "required": [ "case_reference", "customer_reference", "title", "description", "status", "priority", "category", "assignee_user_id", "channel", "created_at", "updated_at", "resolved_at", "closed_at" ], "properties": { "case_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "customer_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "action_required", "awaiting_external_response", "billing_blocked", "manual_follow_up", "resolved", "cancelled", "closed" ] }, "priority": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "assignee_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "channel": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StaffCaseDetail": { "type": "object", "additionalProperties": false, "required": [ "case_reference", "customer_reference", "title", "description", "status", "priority", "category", "assignee_user_id", "channel", "created_at", "updated_at", "resolved_at", "closed_at", "events", "attachments", "events_page", "attachments_page" ], "properties": { "case_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "customer_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "action_required", "awaiting_external_response", "billing_blocked", "manual_follow_up", "resolved", "cancelled", "closed" ] }, "priority": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "assignee_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "channel": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCaseEvent" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/StaffAttachment" } }, "events_page": { "$ref": "#/components/schemas/StaffCasePage" }, "attachments_page": { "$ref": "#/components/schemas/StaffCasePage" } } }, "StaffCaseEvent": { "type": "object", "additionalProperties": false, "required": [ "event_reference", "event_type", "message", "visibility", "author_type", "author_user_id", "channel", "kind", "direction", "verification_method", "verification_reference", "representative", "created_at" ], "properties": { "event_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "event_type": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "customer", "internal" ] }, "author_type": { "type": "string", "enum": [ "customer", "staff" ] }, "author_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "channel": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ], "enum": [ "message", "phone_summary", null ] }, "direction": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "verification_reference": { "type": [ "string", "null" ] }, "representative": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "name", "mandate_reference" ], "properties": { "name": { "type": [ "string", "null" ] }, "mandate_reference": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } } }, "StaffCaseCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "customer_reference", "title" ], "properties": { "customer_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque resource reference. Access always requires the organization credential and authorized staff identity." }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "type": [ "string", "null" ], "maxLength": 8000 }, "category": { "type": [ "string", "null" ], "maxLength": 120 }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } } }, "StaffMessageRequest": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 8000 }, "kind": { "type": "string", "enum": [ "message", "phone_summary" ] } } }, "StaffNoteRequest": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "StaffPhoneRequest": { "type": "object", "additionalProperties": false, "required": [ "direction", "summary", "verification_method" ], "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 8000 }, "verification_method": { "type": "string", "enum": [ "unverified", "strong_eid", "authenticated_portal_confirmation", "callback_registered_number" ] }, "verification_reference": { "type": [ "string", "null" ], "maxLength": 120 }, "representative": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ], "maxLength": 160 }, "mandate_reference": { "type": [ "string", "null" ], "maxLength": 120 } } }, { "type": "null" } ] } } }, "StaffStatusRequest": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "action_required", "awaiting_external_response", "manual_follow_up", "resolved", "closed" ] }, "message": { "type": [ "string", "null" ], "maxLength": 8000 } } }, "StaffAssigneeRequest": { "type": "object", "additionalProperties": false, "required": [ "assignee_user_id" ], "properties": { "assignee_user_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "StaffAttachment": { "type": "object", "additionalProperties": false, "required": [ "attachment_reference", "file_name", "mime_type", "byte_size", "sha256", "uploaded_by", "created_at", "visibility", "scan_status", "scan_reason" ], "properties": { "attachment_reference": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}_[A-Za-z0-9_-]{20,64}$", "description": "Opaque public reference. It identifies the attachment but grants no access on its own." }, "file_name": { "type": "string", "maxLength": 160, "description": "Sanitized file name; the extension always matches the detected type." }, "mime_type": { "type": [ "string", "null" ], "enum": [ "application/pdf", "image/png", "image/jpeg", null ] }, "byte_size": { "type": "integer", "minimum": 1, "maximum": 4194304 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the stored bytes; re-verified on every download." }, "uploaded_by": { "type": "string", "enum": [ "customer", "staff" ] }, "created_at": { "type": "string", "format": "date-time" }, "visibility": { "type": "string", "enum": [ "customer", "internal" ] }, "scan_status": { "type": "string", "enum": [ "quarantined", "released", "rejected" ] }, "scan_reason": { "type": [ "string", "null" ] } } }, "getApiV1StaffUsersResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffAccount" } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" }, "pagination": { "$ref": "#/components/schemas/StaffPagination" } } }, "postApiV1StaffUsersResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffInviteResult" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "patchApiV1StaffUsersIdResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffAccountState" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "postApiV1StaffUsersIdDisableResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffAccountState" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "postApiV1StaffUsersIdEnableResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffAccountState" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffRolesResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffRole" } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffCustomersResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "customers", "pagination" ], "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCustomerSummary" } }, "pagination": { "$ref": "#/components/schemas/StaffCustomerPagination" } } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffCustomersRefResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "customer" ], "properties": { "customer": { "$ref": "#/components/schemas/StaffCustomer" } } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "patchApiV1StaffCustomersRefContactResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffContactChangeResult" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "postApiV1StaffCustomersRefIdentityChangeResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffIdentityChangeResult" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffCasesResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCase" } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" }, "page": { "$ref": "#/components/schemas/StaffCasePage" } } }, "postApiV1StaffCasesResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCase" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffCasesReferenceResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCaseDetail" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "postApiV1StaffCasesReferenceMessagesResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCaseEvent" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "postApiV1StaffCasesReferenceNotesResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCaseEvent" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "postApiV1StaffCasesReferencePhoneInteractionsResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCaseEvent" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "patchApiV1StaffCasesReferenceStatusResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCase" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "patchApiV1StaffCasesReferenceAssigneeResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffCase" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffCasesReferenceAttachmentsResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffAttachment" } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" }, "page": { "$ref": "#/components/schemas/StaffCasePage" } } }, "postApiV1StaffCasesReferenceAttachmentsResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": { "$ref": "#/components/schemas/StaffAttachment" }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "getApiV1StaffCasesReferenceAttachmentsAttachmentReferenceFileResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version" ], "properties": { "data": {}, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } } }, "StaffCasePage": { "type": "object", "additionalProperties": false, "required": [ "limit", "offset", "returned", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "const": 0 }, "returned": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "StaffEnableRequest": { "type": "object", "additionalProperties": false, "properties": {} }, "ErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error", "request_id", "correlation_id", "contract_schema_version" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "retryable", "field", "blockers" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "stage": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "hint": { "type": "string" }, "retryable": { "type": "boolean" }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/ApiBlocker" } }, "details": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } }, "request_id": { "type": "string" }, "correlation_id": { "type": "string" }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" } }, "description": "Canonical error envelope. Business and provider failures use one nested error object; no parallel top-level aliases are emitted." }, "StaffEmbeddedCollectionPage": { "type": "object", "additionalProperties": false, "required": [ "limit", "returned", "has_more" ], "properties": { "limit": { "type": "integer", "const": 100 }, "returned": { "type": "integer", "minimum": 0, "maximum": 100 }, "has_more": { "type": "boolean" } }, "description": "Bounded initial customer collection. has_more explicitly indicates additional records beyond this initial collection." }, "getApiV1StaffCasesReferenceEventsResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "request_id", "contract_schema_version", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCaseEvent" } }, "request_id": { "type": "string" }, "correlation_id": { "type": [ "string", "null" ] }, "contract_schema_version": { "type": "string", "const": "2026-10-09.1" }, "page": { "$ref": "#/components/schemas/StaffCasePage" } } } }, "responses": { "OrganizationGone": { "description": "Organization is closed or inactive. Error codes: organization_closed, organization_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } } }, "OrganizationPaused": { "description": "Organization API access is paused. Error codes: organization_paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } } }, "PayloadTooLarge": { "description": "JSON body exceeds the allowed size (payload_too_large).", "headers": { "X-Gridex-Contract-Version": { "$ref": "#/components/headers/GridexContractVersion" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Gridex-Documentation-Version": { "$ref": "#/components/headers/GridexDocumentationVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "x-error-codes": [ "api_contract_profile_unavailable" ] }