{ "openapi": "3.1.0", "info": { "title": "NOMOI appliance management API", "version": "0.1.0", "description": "Appliance API: bootstrap, tenant authentication and its operator login gate, scope authorization, durable tenant provisioning, identity registrations, policy drafts, serialized asynchronous publications, suspension and audit history. Tenant creation explicitly enrolls the supplied initial administrator public key; it never imports the operator identity. JSON metadata does not redefine signed protocol identity." }, "servers": [ { "url": "/api/v1" } ], "paths": { "/verifiers": { "get": { "operationId": "listVerifiers", "summary": "List public Trust Anchor verifiers", "description": "Ready tenants that opted into public listing, plus the private ready tenant of the currently authenticated administrator. Ordered by scope prefix and IPNS ID. Includes only scope_prefix and ipns_id. Suspended, failed and provisioning tenants are excluded. Direct verifier URLs remain usable regardless of listing visibility.", "x-implementation-phase": 7, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Public verifier directory", "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": ["scope_prefix", "ipns_id"], "additionalProperties": false, "properties": { "scope_prefix": { "type": "string" }, "ipns_id": { "type": "string" } } } } } } } } }, "503": { "description": "Verifier directory unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "health", "description": "See platform API integration guide.", "x-implementation-phase": 1, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ready": { "get": { "operationId": "readiness", "summary": "readiness", "description": "Bounded aggregate readiness: metadata, bootstrap, shared Kubo identity, expected tenant workers and pending/retrying publications. Pending jobs and unavailable dependencies return 503. Suspended workers are excluded. No customer identifiers are exposed.", "x-implementation-phase": 1, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not ready", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Readiness" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi", "summary": "openapi", "description": "The OpenAPI document itself.", "x-implementation-phase": 1, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bootstrap": { "get": { "operationId": "bootstrapStatus", "summary": "bootstrapStatus", "description": "Public setup state, operator identifier and authentication scope, current publication progress and retry diagnostics. Poll until awaiting_enrollment, then enroll; poll until awaiting_nomoi_login before authenticating.", "x-implementation-phase": 3, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapStatus" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bootstrap/sessions": { "post": { "operationId": "bootstrapAuthenticate", "summary": "bootstrapAuthenticate", "description": "See platform API integration guide.", "x-implementation-phase": 3, "x-authorization": { "mode": "public" }, "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapSession" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapCredentials" } } } } } }, "/bootstrap/enrollment": { "post": { "operationId": "bootstrapEnroll", "summary": "bootstrapEnroll", "description": "See platform API integration guide.", "x-implementation-phase": 3, "x-authorization": { "mode": "bootstrap" }, "security": [ { "bootstrapBearer": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResult" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/login-attempts": { "post": { "operationId": "beginLogin", "summary": "beginLogin", "description": "Select only a ready tenant from the trusted registry; verify its exact authentication or administration scope and capture leaf, subject, algorithm, nonce and chain expiry. Until bootstrap is active, operator login requires the enrolled subject. Cookie transport requires the configured Origin and sets a separate HttpOnly browser-binding cookie for this attempt; bearer transport returns an opaque binding token without cookies.", "x-implementation-phase": 4, "x-authorization": { "mode": "public", "scope_template": ".nomos.web.auth", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The selected tenant must be ready.", "context_requirements": [ "Prove possession through the selected tenant challenge-response flow." ], "administration_scope_template": ".nomos.web" }, "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAttempt" } } }, "headers": { "Set-Cookie": { "description": "Cookie transport only: HttpOnly, SameSite=Strict, Path=/, Secure for HTTPS. Begin sets an attempt-specific binding; completion clears it and rotates the session.", "schema": { "type": "string" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } } ] } }, "/tenants/{tenant_id}/login-attempts/{attempt_id}/response": { "post": { "operationId": "completeLogin", "summary": "completeLogin", "description": "Submit only signature and binding_token. Cookie attempts additionally require their browser-binding cookie and configured Origin. Atomically claim the attempt, consume the stored nonce on its original verifier, revalidate the original mandate and create one session. Failed/interrupted proof consumes the attempt. First enrolled-operator login permanently closes bootstrap. Cookie completion sets a new session cookie and returns csrf_token without a bearer token.", "x-implementation-phase": 4, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResult" } } }, "headers": { "Set-Cookie": { "description": "Cookie transport only: HttpOnly, SameSite=Strict, Path=/, Secure for HTTPS. Begin sets an attempt-specific binding; completion clears it and rotates the session.", "schema": { "type": "string" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "attempt_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } } ] } }, "/session": { "get": { "operationId": "currentSession", "summary": "currentSession", "description": "Revalidate the stored login mandate on every read using its selected tenant verifier. Confirmed rejection invalidates the session; infrastructure failure returns inconclusive 503 and retains it for retry. Sessions expire after at most one hour, bounded by the earliest chain expiry. Cookie responses include the session CSRF token. No management authority is implied.", "x-implementation-phase": 4, "x-authorization": { "mode": "session" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] }, { "localSessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/session/logout": { "post": { "operationId": "logout", "summary": "logout", "description": "Delete the application session. Cookie requests require the configured Origin and X-CSRF-Token. Does not contact the verifier, so logout remains available during outages. Bearer and cookie credentials cannot be interchanged or combined.", "x-implementation-phase": 4, "x-authorization": { "mode": "session" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] }, { "localSessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required with cookie transport. Obtain the session-bound value from login completion or GET /session.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants": { "get": { "operationId": "listTenants", "summary": "listTenants", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tenant.read", "matching": "exact", "authorizing_tenant": "operator", "resource_constraint": "The operator manages registered tenants; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "createTenant", "summary": "createTenant", "description": "Reserve a durable provisioning job and explicitly enroll the supplied initial administrator. Reusing Idempotency-Key with the same input returns the original response; different input returns 409. Poll GET /tenants/{tenant_id} for progress and verifier readiness.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tenant.add", "matching": "exact", "authorizing_tenant": "operator", "resource_constraint": "The operator manages registered tenants; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCreate" } } } }, "parameters": [ { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/identities": { "get": { "operationId": "listIdentities", "summary": "listIdentities", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.identity.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "registerIdentity", "summary": "registerIdentity", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.identity.add", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/identities/{identity_id}": { "delete": { "operationId": "removeIdentity", "summary": "Remove a public identity registration", "description": "Removes an identity from this tenant's registration list. Enrolled administrators and identities in the current policy or a pending publication cannot be removed. Removing a registration does not revoke a published mandate or Trust Anchor; change and publish the policy to withdraw authority.", "x-implementation-phase": 7, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.identity.remove", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and identity registration must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "identity_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact identity.remove action grant.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The registration was removed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "identity_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": ["identity_id", "removed"] } } } }, "default": { "description": "Application failure; published or enrolled identities return identity_in_use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tenants/{tenant_id}/publications": { "get": { "operationId": "listPublications", "summary": "listPublications", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJobList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "publishDraft", "summary": "publishDraft", "description": "Freeze the requested draft revision in a durable publication job. One job may be pending per tenant; competing requests or stale draft bases return 409. Reusing the same Idempotency-Key returns the original job. Publication happens asynchronously.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.ta.publish", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "resources": [ { "kind": "ta_draft", "body_field": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJob" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRequest" } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/audit-events": { "get": { "operationId": "listAuditEvents", "summary": "listAuditEvents", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.audit.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/tenants/{tenant_id}": { "get": { "operationId": "getTenant", "summary": "getTenant", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tenant.read", "matching": "exact", "authorizing_tenant": "operator", "resource_constraint": "The operator manages registered tenants; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "operationId": "setTenantState", "summary": "setTenantState", "description": "Suspension retains all data. Resumption uses the same permission. The operator tenant cannot be suspended through this route.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tenant.suspend", "matching": "exact", "authorizing_tenant": "operator", "resource_constraint": "The operator manages registered tenants; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "tenant.suspend authorizes both suspension and resumption of ordinary tenants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantState" } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/auth": { "patch": { "operationId": "setTenantAuth", "summary": "Set platform login access for a Trust Anchor", "description": "Customer TA login is disabled by default. This gate affects new login attempts, not existing sessions, verifier routing, or published policy. The operator TA remains enabled.", "x-implementation-phase": 7, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tenant.auth", "matching": "exact", "authorizing_tenant": "operator", "resource_constraint": "Only fully provisioned customer TAs may change platform login access; the operator TA remains enabled.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the operator tenant." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Updated TA", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Tenant"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TenantAuth"}}}}, "parameters": [ {"name": "tenant_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Required for login-only sessions using a tenant.auth action grant.", "schema": {"type": "string", "minLength": 1}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport.", "schema": {"type": "string", "minLength": 1}} ] } }, "/tenants/{tenant_id}/verifier-visibility": { "get": { "operationId": "getVerifierVisibility", "summary": "Read verifier directory visibility", "x-implementation-phase": 7, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.verifier.visibility", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and setting must belong to the target tenant.", "context_requirements": ["Reverify the tenant session on every read.", "The session must belong to the target tenant."], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "parameters": [{"name": "tenant_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": { "200": {"description": "Current setting", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifierVisibility"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } }, "patch": { "operationId": "setVerifierVisibility", "summary": "Set verifier directory visibility", "x-implementation-phase": 7, "description": "Only the target Trust Anchor administrator or an exact verifier.visibility action grant can change this setting. Revision conflicts return 409. This changes directory listing, not direct verifier access.", "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.verifier.visibility", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and setting must belong to the target tenant.", "context_requirements": ["Reverify the tenant session and any action grant.", "The session must belong to the target tenant."], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "parameters": [{"name": "tenant_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "schema": {"type": "string"}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifierVisibility"}}}}, "responses": { "200": {"description": "Updated setting", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifierVisibility"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/tenants/{tenant_id}/scope-schema": { "get": { "operationId": "getScopeSchema", "summary": "getScopeSchema", "description": "See platform API integration guide.", "x-implementation-phase": 5, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.schema.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeSchema" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/ta": { "get": { "operationId": "getTrustAnchor", "summary": "getTrustAnchor", "description": "Read the selected tenant's published Trust Anchor policy. A verified session for that tenant may read it; editing and publishing still require administration or action authority.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "session_read": true, "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "When an action mandate is supplied, its subject and algorithm must match the authenticated session.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session for the target tenant may read its published Trust Anchor policy. Editing and publishing require administration or exact action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustAnchor" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/ta/drafts": { "post": { "operationId": "createDraft", "summary": "createDraft", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/ta/drafts/{draft_id}": { "get": { "operationId": "getDraft", "summary": "getDraft", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] }, "put": { "operationId": "editDraft", "summary": "editDraft", "description": "Replace policy fields with revision conflict protection. A tenant administration session covers all fields; auth-only sessions require ta.edit and the additional per-field action authorities.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Without an administration session, every submitted policy field requires its additional mandate, even if unchanged; null is always invalid.", "The session must belong to the authorizing tenant." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "additional_scopes_on_fields": { "root_identity_ids": ".nomos.web.identity.add", "whitelist": ".nomos.web.whitelist.edit", "revocations": ".nomos.web.revoke.add" }, "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraftEdit" } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tenants/{tenant_id}/publications/{job_id}": { "get": { "operationId": "getPublication", "summary": "getPublication", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "tenant", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_tenant": "target", "resource_constraint": "The session and all referenced resources must belong to the target tenant.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing tenant, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing tenant." ], "resources": [ { "kind": "publication", "parameter": "job_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJob" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/login-attempts": { "post": { "operationId": "discoverLogin", "summary": "Start login using the mandate Trust Anchor", "description": "Infer the tenant from the presented leaf mandate Trust Anchor, matching only the trusted tenant registry. Accepts CID and PEM presentations. Then apply the same tenant readiness, verification, scope, enrollment and browser binding checks as tenant-specific login.", "x-implementation-phase": 4, "x-authorization": { "mode": "public" }, "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAttempt" } } }, "headers": { "Set-Cookie": { "description": "Cookie transport only: HttpOnly, SameSite=Strict, Path=/, Secure for HTTPS. Begin sets an attempt-specific binding; completion clears it and rotates the session.", "schema": { "type": "string" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "bootstrapBearer": { "type": "http", "scheme": "bearer", "description": "Setup-only credential, permanently disabled after operator NOMOI login." }, "sessionBearer": { "type": "http", "scheme": "bearer" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-nomos_session", "description": "HTTPS cookie: Secure, HttpOnly, SameSite=Strict, Path=/, no Domain. Cookie mutations require Origin and the session CSRF token." }, "localSessionCookie": { "type": "apiKey", "in": "cookie", "name": "nomos_session", "description": "Loopback HTTP development only. Same protections as the HTTPS cookie except Secure and the __Host- prefix." } }, "schemas": { "Outcome": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "outcome": { "const": "accepted" }, "code": { "const": 0 } }, "required": [ "outcome", "code" ] }, { "type": "object", "additionalProperties": false, "properties": { "outcome": { "const": "rejected" }, "code": { "type": "integer", "minimum": 1, "maximum": 4294967295 } }, "required": [ "outcome", "code" ] }, { "type": "object", "additionalProperties": false, "properties": { "outcome": { "const": "inconclusive" } }, "required": [ "outcome" ] } ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "verification": { "$ref": "#/components/schemas/Outcome" } }, "required": [ "kind", "message" ] } }, "required": [ "error" ] }, "Health": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] }, "Readiness": { "type": "object", "additionalProperties": false, "properties": { "api": { "type": "string", "enum": [ "ready" ] }, "metadata": { "type": "string", "enum": [ "ready" ] }, "bootstrap": { "type": "string", "enum": [ "not_implemented", "provisioning", "awaiting_enrollment", "awaiting_nomoi_login", "active" ] }, "ready": { "type": "boolean" }, "kubo": { "type": "string", "enum": [ "ready", "unavailable" ] }, "workers": { "type": "object", "additionalProperties": false, "properties": { "expected": { "type": "integer", "minimum": 0 }, "ready": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 } }, "required": [ "expected", "ready", "unavailable" ] }, "publications": { "type": "object", "additionalProperties": false, "properties": { "pending": { "type": "integer", "minimum": 0 }, "retrying": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "retrying" ] } }, "required": [ "api", "metadata", "bootstrap", "ready" ] }, "BootstrapStatus": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "provisioning", "awaiting_enrollment", "awaiting_nomoi_login", "active" ] }, "operator_tenant_id": { "type": "string", "minLength": 1 }, "default_password_enabled": { "type": "boolean" }, "publication": { "$ref": "#/components/schemas/PublicationJob" }, "operator_ipns_id": { "type": "string", "description": "Canonical bare Kubo self IPNS ID; empty before discovery." }, "management_prefix": { "type": "string" }, "auth_scope": { "type": "string" }, "last_error": { "type": "string", "description": "Diagnostic for retryable provisioning or publication failure; never a NOMOI verdict." }, "administration_scope": { "type": "string", "description": "Present a mandate with this exact scope to sign in and administer the operator tenant." } }, "required": [ "state", "default_password_enabled", "operator_tenant_id", "operator_ipns_id", "management_prefix", "auth_scope", "publication", "administration_scope" ] }, "BootstrapCredentials": { "type": "object", "additionalProperties": false, "properties": { "password": { "type": "string", "minLength": 1, "writeOnly": true } }, "required": [ "password" ] }, "BootstrapSession": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "token", "expires_at" ], "description": "Opaque setup bearer credential, valid for 15 minutes and invalidated permanently at first successful operator login." }, "Enrollment": { "type": "object", "additionalProperties": false, "properties": { "public_key": { "type": "string", "contentEncoding": "base64" }, "algorithm": { "type": "string", "minLength": 1 } }, "required": [ "public_key", "algorithm" ] }, "EnrollmentResult": { "type": "object", "additionalProperties": false, "properties": { "identity": { "$ref": "#/components/schemas/Identity" }, "publication": { "$ref": "#/components/schemas/PublicationJob" } }, "required": [ "identity", "publication" ] }, "Tenant": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ipns_id": { "type": "string", "description": "Canonical bare Kubo IPNS publishing-key ID; assigned by Kubo, never selected by request." }, "scope_prefix": { "type": "string", "minLength": 1 }, "operator": { "type": "boolean" }, "state": { "type": "string", "enum": [ "provisioning", "ready", "failed", "suspended" ] }, "provisioning_step": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "publication": { "$ref": "#/components/schemas/PublicationJob" }, "last_error": { "type": "string" }, "verifier_public": { "type": "boolean", "description": "Whether the verifier appears in the public dropdown; defaults to false." }, "auth_enabled": { "type": "boolean", "description": "Whether this TA accepts new platform login attempts. Customer TAs default to false; the operator TA remains true." }, "auth_revision": { "type": "integer", "minimum": 1, "description": "Revision of the login gate, independent of the TA lifecycle revision." }, "verifier_ready": { "type": "boolean", "description": "Current verifier probe, present on individual tenant reads." } }, "required": [ "id", "scope_prefix", "operator", "state", "provisioning_step", "revision", "verifier_public", "auth_enabled", "auth_revision" ] }, "TenantCreate": { "type": "object", "additionalProperties": false, "properties": { "scope_prefix": { "type": "string", "minLength": 1 }, "administrator": { "$ref": "#/components/schemas/Enrollment" } }, "required": [ "scope_prefix", "administrator" ], "description": "The designated administrator is enrolled as the initial root signer for scope_prefix. Supply only its public key. Idempotency-Key is scoped to the operator tenant, authenticated subject and algorithm, and operation." }, "VerifierVisibility": { "type": "object", "additionalProperties": false, "properties": { "public": {"type": "boolean"}, "revision": {"type": "integer", "minimum": 1} }, "required": ["public", "revision"] }, "TenantAuth": { "type": "object", "additionalProperties": false, "properties": { "enabled": {"type": "boolean"}, "revision": {"type": "integer", "minimum": 1, "description": "Current auth_revision from the TA response."} }, "required": ["enabled", "revision"] }, "TenantState": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "suspended", "ready" ] }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "state", "revision" ] }, "Identity": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "tenant_id": { "type": "string", "minLength": 1 }, "public_key": { "type": "string", "contentEncoding": "base64" }, "algorithm": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "tenant_id", "public_key", "algorithm", "revision" ] }, "MandateInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "cid": { "type": "string", "minLength": 1 } }, "required": [ "cid" ] }, { "type": "object", "additionalProperties": false, "properties": { "presentation": { "type": "string", "minLength": 1, "description": "PEM presentation containing canonical signed bytes." } }, "required": [ "presentation" ] } ] }, "LoginRequest": { "type": "object", "additionalProperties": false, "properties": { "mandate": { "$ref": "#/components/schemas/MandateInput" }, "transport": { "type": "string", "enum": [ "cookie", "bearer" ], "description": "Cookie binds to this browser and configured Origin. Bearer is an explicit remote API transport; the same verification and session policy apply." } }, "required": [ "mandate", "transport" ] }, "LoginAttempt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "tenant_id": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "pending", "completed", "expired", "failed" ] }, "nonce": { "type": "string", "contentEncoding": "base64" }, "mandate_cid": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "binding_token": { "type": "string", "description": "Opaque application correlation secret; required with signature. Never a caller-selected nonce." }, "presentation": { "type": "string", "description": "The challenged leaf mandate as an inline NOMOI presentation PEM, however it was presented. A browser holding the leaf subject key signs the challenge over its envelope after checking that it is mandate_cid. Absent when the verifier did not return the envelope." } }, "required": [ "id", "tenant_id", "state", "nonce", "mandate_cid", "expires_at", "binding_token" ], "description": "Pending login expires after at most 30 seconds, bounded by the earliest chain expiry. Wrong binding does not claim the attempt; failed or interrupted proof does. Begin a new attempt to retry." }, "LoginResponse": { "type": "object", "additionalProperties": false, "properties": { "signature": { "type": "string", "contentEncoding": "base64" }, "binding_token": { "type": "string", "minLength": 1 } }, "required": [ "signature", "binding_token" ] }, "Session": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "tenant_id": { "type": "string", "minLength": 1 }, "ipns_id": { "type": "string", "minLength": 1, "description": "Bare IPNS publishing-key ID of the authenticated tenant." }, "scope_prefix": { "type": "string", "minLength": 1, "description": "Trust Anchor scope prefix of the authenticated tenant." }, "subject": { "type": "string", "contentEncoding": "base64" }, "subject_algorithm": { "type": "string", "minLength": 1 }, "mandate_cid": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "csrf_token": { "type": "string", "description": "Cookie sessions only. Required as X-CSRF-Token on session mutations." }, "scope": { "type": "string", "description": "Exact scope of the mandate presented at sign-in." }, "administration": { "type": "boolean", "description": "Management authority derived from the verified mandate scope or the enrolled administrator subject and algorithm of that tenant. Recomputed on session revalidation." } }, "required": [ "id", "tenant_id", "ipns_id", "scope_prefix", "subject", "subject_algorithm", "mandate_cid", "expires_at", "scope", "administration" ] }, "SessionResult": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/Session" }, "token": { "type": "string", "description": "Bearer transport only. Store securely; session secrets are hashed in metadata. Expires after at most one hour, bounded by the earliest chain expiry." }, "csrf_token": { "type": "string", "description": "Cookie transport only; the session secret is delivered solely by Set-Cookie." } }, "required": [ "session" ], "oneOf": [ { "required": [ "token" ] }, { "required": [ "csrf_token" ] } ] }, "ScopeOperation": { "type": "object", "additionalProperties": false, "properties": { "operation_id": { "type": "string", "minLength": 1 }, "scope_template": { "type": "string", "minLength": 1 }, "matching": { "type": "string", "enum": [ "exact" ] }, "authorizing_tenant": { "type": "string", "enum": [ "operator", "target" ] }, "resource_constraint": { "type": "string" }, "context_requirements": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "public", "operator", "tenant" ] }, "method": { "type": "string" }, "path": { "type": "string" }, "additional_scopes_on_fields": { "type": "object", "additionalProperties": { "type": "string" } }, "session_read": { "type": "boolean", "description": "A verified session of the target tenant may read this operation without a separate action mandate." }, "resources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "parameter": { "type": "string" }, "body_field": { "type": "string" } }, "required": [ "kind" ] } }, "administration_scope_template": { "type": "string", "const": ".nomos.web" } }, "required": [ "operation_id", "scope_template", "matching", "authorizing_tenant", "resource_constraint", "context_requirements", "mode", "method", "path", "administration_scope_template" ] }, "ScopeSchema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeOperation" } } }, "required": [ "id", "version", "operations" ] }, "TrustAnchor": { "type": "object", "additionalProperties": false, "properties": { "tenant_id": { "type": "string", "minLength": 1 }, "published_cid": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } }, "mandate_expiry": { "type": "object", "description": "ExpiresAt of each revoked mandate the server could retrieve, keyed by mandate CID. An absent CID means its expiry is unknown: its revocation can still be removed (§5.3.1), but nothing confirms the mandate has expired.", "additionalProperties": { "type": "string", "format": "date-time" } } }, "required": [ "tenant_id", "revision", "root_identity_ids", "whitelist", "revocations", "mandate_expiry" ] }, "WhitelistEntry": { "type": "object", "additionalProperties": false, "properties": { "ipns_id": { "type": "string", "minLength": 1 }, "scope_prefix": { "type": "string", "minLength": 1 } }, "required": [ "ipns_id", "scope_prefix" ] }, "Revocation": { "type": "object", "description": "Revocations are not permanent (§5.3.1). Removing an identity revocation lifts it at any time. Removing a mandate revocation from the published policy fails with revocation_in_force while the server can read the mandate and finds it within its ExpiresAt. A mandate the server cannot retrieve has no known expiry, and its revocation is removed on the administrator's word.", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "identity", "mandate" ] }, "identifier": { "type": "string", "minLength": 1 } }, "required": [ "kind", "identifier" ] }, "TADraftEdit": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } }, "action_authorities": { "type": "object", "additionalProperties": false, "properties": { "identity.add": { "$ref": "#/components/schemas/MandateInput" }, "whitelist.edit": { "$ref": "#/components/schemas/MandateInput" }, "revoke.add": { "$ref": "#/components/schemas/MandateInput" } } } }, "required": [ "revision", "root_identity_ids", "whitelist", "revocations" ] }, "TADraft": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "tenant_id": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 }, "base_published_cid": { "type": "string", "minLength": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } } }, "required": [ "id", "tenant_id", "revision", "root_identity_ids", "whitelist", "revocations" ] }, "PublicationRequest": { "type": "object", "additionalProperties": false, "properties": { "draft_id": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "draft_id", "revision" ] }, "PublicationJob": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "tenant_id": { "type": "string", "minLength": 1 }, "draft_id": { "type": "string", "minLength": 1 }, "draft_revision": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "queued", "preparing", "publishing", "published", "observed", "failed" ] }, "published_cid": { "type": "string", "minLength": 1 }, "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "Retryable diagnostics; state retains the last completed stage and the job resumes automatically. A suspended tenant pauses work." } }, "required": [ "id", "tenant_id", "draft_id", "draft_revision", "state" ] }, "ErrorDetail": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "verification": { "$ref": "#/components/schemas/Outcome" } }, "required": [ "kind", "message" ] }, "AuditEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "tenant_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_subject": { "type": "string", "contentEncoding": "base64" }, "actor_algorithm": { "type": "string", "minLength": 1 }, "action": { "type": "string", "minLength": 1 }, "mandate_cid": { "type": "string", "minLength": 1 }, "result": { "type": "string" }, "publication_job_id": { "type": "string", "minLength": 1 }, "published_cid": { "type": "string" }, "resource_id": { "type": "string" }, "local_operator": { "type": "string", "description": "Local OS uid for an offline recovery action." }, "reason": { "type": "string", "maxLength": 512 } }, "required": [ "id", "tenant_id", "occurred_at", "action", "result" ] }, "TenantList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] }, "IdentityList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] }, "PublicationJobList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationJob" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] }, "AuditEventList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] } } }, "x-scope-schema": { "id": "nomos.management", "version": 7 } }