{ "openapi": "3.0.0", "info": { "title": "NodeJS CaaS service", "version": "2.1", "license": {} }, "paths": { "/sd": { "patch": { "summary": "Create, update or delete service directories.", "description": "Create, update, delete service directories.\n- Key must be active with authLevel **system**.\n- Set empty string, null or false to remove service directory.\n- **licenses** service directory is not allowed to be removed.\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### JSON (required)\nThe JSON object to create, update or remove existing service directories.\n\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns the all updated service directories.
\nThis API throws an error if something goes wrong.\n", "tags": [ "Service Directory" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetServiceComponentsRequest" } } } }, "responses": { "200": { "description": "All updated service directories." }, "400": { "description": "Bad Request, Validation errors." }, "401": { "description": "Unauthorized" } } }, "get": { "summary": "Get all service directories.", "description": "Get all service directories.

\nIf the API is call on **internal path** OR **internal_sd=true** then it will return internal URLs\nIf the API is call on **external_sd=true** then it will return external URLs\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns all service directories.\n", "tags": [ "Service Directory" ], "parameters": [ { "name": "internal_sd", "in": "query", "description": "internal_sd is used to generate internal URLs.", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "external_sd", "in": "query", "description": "external_sd is used to generate external URLs.", "required": false, "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetServiceComponentsResponse" } } } } } } }, "/tenants/{tenantId}/community/{communityId}/secrets": { "put": { "summary": "Create a new secret", "description": "Create a new secret with encrypted value storage.\n- Key must be active with authLevel **system**, **service**, or **service_ext**.\n- The combination of {tenantId, communityId, tag} must be unique.\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### tag (required)\nSecret identifier. Must start with a letter [a-zA-Z] and contain only [a-zA-Z0-9_]\n\n### value (required)\nSecret value to be encrypted and stored\n\n### createdBy (required)\nUser or service that created the secret\n\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns secret metadata (tag, createdBy, createdTs) without the value.
\nThis API throws an error if something goes wrong.\n", "tags": [ "Secret Store" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "example": "tenant_123" } }, { "name": "communityId", "in": "path", "description": "Community identifier", "required": true, "schema": { "type": "string", "example": "community_456" } }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretRequest" } } } }, "responses": { "201": { "description": "Secret created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretResponse" } } } }, "400": { "description": "Bad Request - Invalid tag format or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing ECDSA signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - Secret with this tag already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenants/{tenantId}/community/{communityId}/secrets/fetch": { "post": { "summary": "Fetch secrets with optional tag filter", "description": "Fetch secrets for a specific tenant and community with optional tag filtering.\n- Key must be active with authLevel **system**, **service**, or **service_ext**.\n- If no tags filter is provided, returns all secrets.\n- If tags filter is provided, returns only matching secrets.\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### tags (optional)\nArray of secret tags to filter. If not provided, returns all secrets.\n\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns array of secrets with decrypted values and metadata.\n", "tags": [ "Secret Store" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "example": "tenant_123" } }, { "name": "communityId", "in": "path", "description": "Community identifier", "required": true, "schema": { "type": "string", "example": "community_456" } }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchSecretsRequest" } } } }, "responses": { "200": { "description": "Secrets fetched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchSecretsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing ECDSA signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenants/{tenantId}/community/{communityId}/secrets/{tag}": { "delete": { "summary": "Delete a secret by tag", "description": "Delete a secret by its tag identifier.\n- Key must be active with authLevel **system**, **service**, or **service_ext**.\n- Once deleted, the secret cannot be recovered.\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns success message.
\nThis API throws an error if the secret is not found.\n", "tags": [ "Secret Store" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "example": "tenant_123" } }, { "name": "communityId", "in": "path", "description": "Community identifier", "required": true, "schema": { "type": "string", "example": "community_456" } }, { "name": "tag", "in": "path", "description": "Secret identifier to delete", "required": true, "schema": { "type": "string", "example": "stripe_api_key" } }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "responses": { "200": { "description": "Secret deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSecretResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing ECDSA signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - Secret does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/publickeys": { "get": { "description": "Get system's public key.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a public key object\n", "tags": [ "Public Key" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyResponse" } } } }, "401": { "description": "Invalid hawk signature / ID found." } } } }, "/healthz": { "get": { "summary": "Get healthz.", "description": "Get healthz
\n\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a healthz object\n - ```version = ..```
\n\n - ```git-tag```: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.\n - ```commit-id```: This is the git-commit-id. eg: When code is built from this, the hex code, in the end, is the commit it.\n - ```dob```: Date Of Build. This is epoc-time-in-se\tconds that tell the time when the build was created.\n - \u200bif the code is not built from a git-tag, then the ```version =\ufffc.```\n", "tags": [ "Healthz" ], "responses": { "200": { "description": "Success\n\n```\n{\n \"status\": \"all services operational\",\n \"publicKey\": \"string\" //same as /publickeys endpoint,\n \"code\": \"200\",\n \"version\": \"\" //as defined above\n}\n```\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthzResponse" } } } } } } }, "/extension/activate": { "post": { "summary": "Activate a browser extension instance", "description": "Activates a browser extension install by binding its UUID to a verified user identity.\nRequest body is ECDSA encrypted. Response is ECDSA encrypted.\n\nAccepts either:\n- **OAuth Bearer token** with `extension:activate` scope (from OIDC PKCE flow)\n- **License key** (system/service/service_ext level)\n\nWhen using OAuth, the `sub` claim from token introspection is recorded as `activatedBy`.\nWhen using license key, the key ID is recorded as `activatedBy`.\n\n| **Headers** |\n|----------------------------------------------|\n\n### Authorization (option 1)\nBearer token with `extension:activate` scope\n\n### licensekey (option 2)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n", "tags": [ "Extension" ], "security": [ { "bearerAuth": [] }, { "keyId": [], "keySecret": [], "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA (alternative to Bearer token) / Try Authorize 🔒", "required": false, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateExtensionRequest" } } } }, "responses": { "200": { "description": "Extension activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateExtensionResponse" } } } }, "400": { "description": "Bad Request \u2014 missing or invalid required fields", "content": { "application/json": { "example": { "code": 400, "message": "extensionId must be a valid GUID" } } } }, "401": { "description": "Unauthorized \u2014 invalid token, insufficient scope, or invalid license key", "content": { "application/json": { "example": { "code": 401, "message": "Insufficient scope" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "code": 500, "message": "Failed to activate extension registration" } } } } } } }, "/extension/status": { "post": { "summary": "Get extension activation status", "description": "Returns the activation status for a given extension ID.\nServer-to-server only \u2014 requires license key (system/service/service_ext).\nRequest body is ECDSA encrypted. Response is ECDSA encrypted.\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n", "tags": [ "Extension" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionStatusRequest" } } } }, "responses": { "200": { "description": "Extension status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionStatusResponse" } } } }, "400": { "description": "Bad Request \u2014 missing or invalid required fields", "content": { "application/json": { "example": { "code": 400, "message": "extensionId must be a valid GUID" } } } }, "401": { "description": "Unauthorized \u2014 invalid or missing license key, or insufficient auth level", "content": { "application/json": { "example": { "code": 401, "message": "Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "code": 500, "message": "Internal Server Error" } } } } } } }, "/extension/deactivate": { "post": { "summary": "Deactivate a browser extension instance", "description": "Deactivates a previously activated extension. Admin-only operation.\nAfter deactivation, the extension will no longer receive session tokens from the workflow API.\nRequires license key (system/service/service_ext).\nRequest body is ECDSA encrypted. Response is ECDSA encrypted.\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n", "tags": [ "Extension" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateExtensionRequest" } } } }, "responses": { "200": { "description": "Extension deactivated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateExtensionResponse" } } } }, "400": { "description": "Bad Request \u2014 missing or invalid required fields", "content": { "application/json": { "example": { "code": 400, "message": "deactivatedBy is required" } } } }, "401": { "description": "Unauthorized \u2014 invalid or missing license key, or insufficient auth level", "content": { "application/json": { "example": { "code": 401, "message": "Unauthorized" } } } }, "404": { "description": "Extension not found for the given extensionId, tenant, and community", "content": { "application/json": { "example": { "code": 404, "message": "Extension not found: 550e8400-e29b-41d4-a716-446655440000" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "code": 500, "message": "Failed to deactivate extension" } } } } } } }, "/environment": { "get": { "description": "Provide details regarding the environments.\n| **Returns** |\n|-------------------------------------------|\n\nReturns an environment object\n", "tags": [ "Environment" ], "responses": { "200": { "description": "Success" } } } }, "/environment/install": { "post": { "summary": ".", "description": "Install environment.\n- Key must be active with authLevel **system** from current license server.. (see /sd)\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### JSON (required)\nThe JSON object to install an environment\n\n\n| **Returns** |\n|----------------------------------------------|\n\ntbd.
\nThis API throws an error if something goes wrong.\n", "tags": [ "Environment" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallEnvironment" } } } }, "responses": { "200": { "description": "tbd." }, "400": { "description": "Bad Request, Validation errors." }, "401": { "description": "Unauthorized" } } } }, "/environment/create/community": { "post": { "summary": ".", "description": "Create Community.\n- Key must be active with authLevel **system/service** from current license server.. (see /sd)\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### JSON (required)\nThe JSON object to install a new community\n\n\n| **Returns** |\n|----------------------------------------------|\n\ntbd.
\nThis API throws an error if something goes wrong.\n", "tags": [ "Environment" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallCommunity" } } } }, "responses": { "200": { "description": "tbd." }, "400": { "description": "Bad Request, Validation errors." }, "401": { "description": "Unauthorized" } } } }, "/ecdsa_helper/{method}": { "post": { "description": "Encrypt and decrypt the data string by public key and private key.\n\n| **Parameters** |\n|----------------------------------------------|\n\n### method (optional)\nThe method parameter is type of enum. Default value is encrypt.
\nThis parameter only accepts following values
\n **encrypt**, **decrypt**\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n\n### dataStr (required)\nThe dataStr key is type of string.\n\n
\n### publicKey (required)\nThe publicKey is type of string.\n\n
\n### privateKey (required)\nThe privateKey is type of string.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns the encrypted/decrypted string.
\nThis API throw an error if something goes wrong. A common source of error is public or private key is not valid.\n", "tags": [ "ECDSA Helper" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcdsaEncryptDecryptRequest" } } } }, "parameters": [ { "in": "path", "name": "method", "schema": { "type": "string", "enum": [ "encrypt", "decrypt" ], "default": "encrypt" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcdsaEncryptDecryptResponse" } } } } } } }, "/tenants/{tenantId}/community/{communityId}/consents/{type}": { "get": { "summary": "Retrieve consent by type", "description": "Retrieve the current consent document for a given type, community, and tenant.\nResponse is ECDSA encrypted. When using swagger (requestfromswagger header), response is returned as plain JSON.\nIf a consent record exists with IPFS content, the content is fetched from IPFS and the signature hash is verified.\nIf no record exists or the record has no IPFS content, a default response is returned with isEnabled set to false and default content fields from the configured template for the given type.\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n", "tags": [ "Consent" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" }, "description": "Tenant identifier" }, { "in": "path", "name": "communityId", "required": true, "schema": { "type": "string" }, "description": "Community identifier" }, { "in": "path", "name": "type", "required": true, "schema": { "type": "string", "enum": [ "biometric" ], "example": "biometric" }, "description": "Consent type (e.g. biometric)" }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "responses": { "200": { "description": "Consent document retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error (e.g. IPFS fetch failure or signature mismatch)" } } } }, "/tenants/{tenantId}/community/{communityId}/consents/ipfs/{ipfsHash}": { "get": { "summary": "Retrieve historical consent by IPFS hash", "description": "Retrieve any historical consent document directly from IPFS by its content hash.\nResponse is ECDSA encrypted. When using swagger (requestfromswagger header), response is returned as plain JSON.\nThis endpoint fetches the document content from IPFS without DB lookup.\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n", "tags": [ "Consent" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" }, "description": "Tenant identifier" }, { "in": "path", "name": "communityId", "required": true, "schema": { "type": "string" }, "description": "Community identifier" }, { "in": "path", "name": "ipfsHash", "required": true, "schema": { "type": "string", "example": "QmAbCdEf123456" }, "description": "IPFS content hash of the consent document" }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "responses": { "200": { "description": "Historical consent document retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "IPFS hash not found" }, "500": { "description": "Internal Server Error" } } } }, "/tenants/{tenantId}/community/{communityId}/consents": { "put": { "summary": "Create or update consent", "description": "Create or update a consent document for a given community and tenant.\nRequest body must be ECDSA encrypted. When using swagger (requestfromswagger header), plain JSON is accepted.\nResponse is ECDSA encrypted. When using swagger, response is returned as plain JSON.\nWhen isEnabled is true and content has changed, the content is written to IPFS with a SHA-512 signature hash and chain linking.\nWhen isEnabled is false, only the enabled flag and audit fields are updated \u2014 no IPFS write occurs and existing hashes are preserved.\nWhen isEnabled is true but content is unchanged, only the enabled flag and audit fields are updated.\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n", "tags": [ "Consent" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" }, "description": "Tenant identifier" }, { "in": "path", "name": "communityId", "required": true, "schema": { "type": "string" }, "description": "Community identifier" }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConsentRequest" } } } }, "responses": { "200": { "description": "Consent document created or updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponse" } } } }, "400": { "description": "Bad Request \u2014 validation errors (e.g. missing title/body/acknowledgeText when isEnabled is true)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/config/{key_path}": { "put": { "summary": "Set configuration", "description": "Set configuration for provided context.\n- If context is {tenantId, communityId} license key must authorized for community, active and not expired and authLevel must be [system, service, service_ext].\n- If context is {personId, mobile_app_id} license key must be active (disable = false) and not expired and authLevel must be [system, service, service_ext, app, app_ext].\n- If context is {appId} license key must be active (disable = false) and not expired, and authLevel must be [system, service, service_ext].\n- In addition {if appId is either 'adminconsole.global' or 'platform'} license key must be active, and authLevel must be [system, service].\n- Additionally add boolean 'internal' to context to limit writes/remove by system/service alone\n\n| **Parameters** |\n|----------------------------------------------|\n\n### key_path (required)\nThe key_path to replace with a new value.
\n- Only alphabets, full stop (.) and underscore (_) is allowed in key_path parameter.\n- To replace full configuration submit \"**data**\" as the value of key_path parameter.\n\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### context (required)\nThe context is a type of object. It will be used to generate a unique key for configuration and will be stored with configuration.\n\n
\n### data (required)\nThe data of the configuration object. Data can be string, number, boolean, array, object.\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns the key path of stored configuration.
\nThis API throws an error if something goes wrong.\n", "tags": [ "Configuration" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "in": "path", "name": "key_path", "schema": { "type": "string", "example": "xxx.xxxx.xxx" } }, { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConfigStoreRequest" } } } }, "responses": { "200": { "description": "Stored key path with values." }, "400": { "description": "Bad Request, Validation errors." }, "401": { "description": "Unauthorized" } } } }, "/config/fetch": { "post": { "summary": "Fetch configuration", "description": "Fetch configuration for provided context and key paths or full configuration.\n
\n- If context is {tenantId, communityId} license key must be authorized for community, active and not expired.\n- If context is {personId, mobile_app_id} license key must be active (disable = false) and not expired.\n- If context is {appId} license key must be active (disable = false) and not expired.\n- In addition {if appId is either 'adminconsole.global' or 'platform'} license key must be active and authLevel must be [system | service | service_ext | app | app_ext]\n- Additionally add boolean 'internal' to context to limit reads by system/service alone\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### context (required)\nThe context is a type of object. It will be used to generate a unique key to find configuration record.\n\n
\n### key_paths (optional)\nThe key_paths of values to fetch.\n- To get full configuration do not specify key_path attribute in request body.\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns the key path and values of stored configuration.
\nThis API throws an error if something goes wrong.\n", "tags": [ "Configuration" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "read_fresh", "in": "query", "description": "read_fresh is used to read fresh data.", "required": false, "schema": { "type": "boolean", "example": true } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchConfigStoreRequest" } } } }, "responses": { "200": { "description": "Returns matched key path with values." }, "400": { "description": "Bad Request, Validation errors." }, "401": { "description": "Unauthorized" } } } }, "/config": { "delete": { "summary": "Remove configuration", "description": "Remove configuration by provided context.\n- If context is {tenantId, communityId} license key must authorized for community, active and not expired and authLevel must be [system, service, service_ext].\n- If context is {personId, mobile_app_id} license key must be active (disable = false) and not expired and authLevel must be [system, service, service_ext, app, app_ext].\n- If context is {appId} license key must be active (disable = false) and not expired and authLevel must be [system, service].\n- In addition {if appId is either 'adminconsole.global' or 'platform'} license key must be active, and authLevel must be [system, service].\n- Additionally add boolean 'internal' to context to limit writes/remove by system alone\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n### context (required)\nThe context is type of object. It will be used to generate unique key for remove configuration.\n\n
\n### key_paths (required)\nThe key_paths is type of array.
\nEach value of array is used to remove key from configuration object.\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns a 204 status code if a valid context and key_paths are provided.\nThis API throws an error if something goes wrong.\n", "tags": [ "Configuration" ], "security": [ { "keyId": [] }, { "keySecret": [] }, { "license": [] } ], "parameters": [ { "name": "licensekey", "in": "header", "description": "License key encrypted with ECDSA / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "requestid", "in": "header", "description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } }, { "name": "publickey", "in": "header", "description": "Public Key / Try Authorize 🔒", "required": true, "schema": { "type": "string", "example": "Do not enter anything, use 'Authorize' fields" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveConfigStoreRequest" } } } }, "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized" }, "404": { "description": "No such a configuration exists" } } } } }, "components": { "schemas": { "PublicKeyResponse": { "type": "object", "properties": { "publicKey": { "type": "string" } }, "example": { "publicKey": "" } }, "HealthzResponse": { "type": "object", "properties": { "status": { "type": "string" }, "publicKey": { "type": "string" }, "code": { "type": "string" }, "version": { "type": "string" } }, "example": { "status": "all services operational", "publicKey": "//same as /publickeys endpoint", "code": "200", "version": "xxxx.xxxx.xxxx" } }, "EcdsaEncryptDecryptRequest": { "type": "object", "properties": { "dataStr": { "type": "string" }, "publicKey": { "type": "string" }, "privateKey": { "type": "string" } }, "example": { "dataStr": "Hey, This is example data string.", "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=", "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=" } }, "EcdsaEncryptDecryptResponse": { "type": "object", "properties": { "data": { "type": "string" } }, "example": { "data": "xxxxxxxxxxxxxxxxxxxx" } }, "SetConfigStoreRequest": { "type": "object", "required": [ "tag" ], "properties": { "context": { "type": "object", "description": "Context object" }, "data": { "type": "object", "description": "Data object" } }, "example": { "context": {}, "data": {} } }, "FetchConfigStoreRequest": { "type": "object", "required": [ "tag" ], "properties": { "context": { "type": "object", "description": "Context object." }, "key_paths": { "type": "array", "description": "Key path array." } }, "example": { "context": {}, "key_paths": [ "xxx", "xxx.xxx", "xxx.xxx.xxx" ] } }, "RemoveConfigStoreRequest": { "type": "object", "required": [ "tag" ], "properties": { "context": { "type": "object", "description": "Context object" }, "key_paths": { "type": "array", "description": "Data array" } }, "example": { "context": {}, "key_paths": [ "xxx.xxx.xx", "xxx" ] } }, "SetServiceComponentsRequest": { "type": "object", "properties": { "name1": { "type": "string" }, "name2": { "type": "string" }, "name3": { "type": "string" } }, "example": { "name1": "https://xxx.xxxxxx.xxx/xxxxx", "name2": "https://xxx.xxxxxx.xxx/xxxxx", "name3": "https://xxx.xxxxxx.xxx/xxxxx" } }, "InstallEnvironment": { "type": "object", "properties": { "instanceType": { "type": "string" }, "rootUrl": { "type": "string" }, "rootLicence": { "type": "string" }, "tenantName": { "type": "string" }, "tenantDNS": { "type": "string" }, "tenantTag": { "type": "string" }, "contactFname": { "type": "string" }, "contactLname": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "tenantPassword": { "type": "string" }, "public_assets_download_url": { "type": "string" }, "smsGateway": { "type": "object", "properties": { "type": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "senderPhone": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "sms", "voice" ] } } } }, "emailGateway": { "type": "object", "properties": { "type": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "serviceUrl": { "type": "string" }, "senderEmail": { "type": "string" }, "port": { "type": "string" }, "protocol": { "type": "string" } } }, "pushConfig": { "type": "object", "description": "Push notification configuration", "properties": { "firebase": { "type": "object", "properties": { "uri": { "type": "string" }, "serviceaccount": { "type": "string" }, "fcmkey": { "type": "string" } } }, "apple": { "type": "object", "properties": { "host": { "type": "string" }, "pkcs8file": { "type": "string" }, "teamid": { "type": "string" }, "keyid": { "type": "string" }, "appname": { "type": "string" } } }, "pushy": { "type": "object", "properties": { "appSecret": { "type": "string" }, "url": { "type": "string" } } }, "behaviorAuth": { "type": "object", "description": "Behavior authentication configuration", "properties": { "provider": { "type": "string" }, "url": { "type": "string" }, "api_key": { "type": "string" }, "api_secret": { "type": "string" }, "auth_type": { "type": "string" } } } } }, "recaptchaConfig": { "type": "object", "description": "Google reCAPTCHA configuration", "properties": { "secret_key_api": { "type": "string" }, "secret_key_ui": { "type": "string" }, "recaptcha_api": { "type": "string" }, "recaptcha_url": { "type": "string" } } }, "analytics": { "type": "object", "properties": { "elastic": { "type": "object", "properties": { "url": { "type": "string" }, "uid": { "type": "string" }, "pwd": { "type": "string" } } } } }, "agentApi": { "type": "object", "description": "Agent API configuration with agent_id as key", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "type": { "type": "string", "description": "HTTP method type", "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "url": { "type": "string", "description": "Agent API endpoint URL" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "none", "basic", "bearer", "api_key", "oauth2" ] }, "credential": { "type": "object", "description": "Credentials based on authType", "properties": { "x-api-key": { "type": "string", "description": "API key for api_key authType" } } } } } } }, "example": { "instanceType": "client-instance", "rootUrl": "https://1k-prod-us.1kosmos.net", "rootLicense": "system|service license from root", "tenantName": "1Kosmos", "tenantDNS": "tenant.1kosmos.net", "tenantTag": "tenanttag", "contactFname": "fname", "contactLname": "lname", "contactEmail": "some@email.com", "contactPhone": "19990009988", "tenantPassword": "******", "public_assets_download_url": "http://ipfs-cluster.static-prod:9095", "smsGateway": { "type": "twilio", "username": "username", "password": "*****", "senderPhone": "1111111111", "channels": [ "sms", "voice" ] }, "emailGateway": { "type": "smtp", "username": "username", "password": "*****", "serviceUrl": "smtp.socketlabs.com", "senderEmail": "no-reply@1kosmos.com", "port": "465", "protocol": "smtp" }, "pushConfig": { "firebase": { "uri": "https://firebase.example.com", "serviceaccount": "/path/to/serviceAccountKey.json", "fcmkey": "AAAA...your_fcm_key" }, "apple": { "host": "api.push.apple.com", "pkcs8file": "/path/to/key.p8", "teamid": "TEAMID123", "keyid": "KEYID456", "appname": "com.example.app" }, "pushy": { "appSecret": "your_pushy_app_secret", "url": "https://api.pushy.me" } }, "behaviorAuth": { "provider": "behavior-provider", "url": "https://behavior.example.com", "api_key": "your_behavior_api_key", "api_secret": "your_behavior_api_secret", "auth_type": "score" }, "recaptchaConfig": { "secret_key_api": "", "secret_key_ui": "", "recaptcha_api": "https://www.google.com/recaptcha/api/siteverify", "recaptcha_url": "https://www.google.com/recaptcha/api.js" }, "analytics": { "elastic": { "url": "https://search-dev-elastic-kk72cvjrv24lxnsneluxl3l6o4.us-west-1.es.amazonaws.com", "uid": "username", "pwd": "password" } }, "agentApi": { "e258cb75-4f8e-47b1-9e18-e949a2f442b0": { "name": "", "type": "", "url": "", "authType": "api_key", "credential": { "x-api-key": "" } } } } }, "InstallCommunity": { "type": "object", "properties": { "communityName": { "type": "string" }, "contactFname": { "type": "string" }, "contactLname": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "communityPassword": { "type": "string" }, "smsGateway": { "type": "object", "properties": { "type": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "senderPhone": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "sms", "voice" ] } } } }, "emailGateway": { "type": "object", "properties": { "type": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "serviceUrl": { "type": "string" }, "senderEmail": { "type": "string" }, "port": { "type": "string" }, "protocol": { "type": "string" } } }, "pushConfig": { "type": "object", "description": "Push notification configuration", "properties": { "firebase": { "type": "object", "properties": { "uri": { "type": "string" }, "serviceaccount": { "type": "string" }, "fcmkey": { "type": "string" } } }, "apple": { "type": "object", "properties": { "host": { "type": "string" }, "pkcs8file": { "type": "string" }, "teamid": { "type": "string" }, "keyid": { "type": "string" }, "appname": { "type": "string" } } }, "pushy": { "type": "object", "properties": { "appSecret": { "type": "string" }, "url": { "type": "string" } } } } } }, "example": { "communityName": "string", "contactFname": "fname", "contactLname": "lname", "contactEmail": "some@email.com", "contactPhone": "19990009988", "communityPassword": "******", "smsGateway": { "type": "twilio", "username": "username", "password": "*****", "senderPhone": "1111111111", "channels": [ "sms", "voice" ] }, "emailGateway": { "type": "smtp", "username": "username", "password": "*****", "serviceUrl": "smtp.socketlabs.com", "senderEmail": "no-reply@1kosmos.com", "port": "465", "protocol": "smtp" }, "pushConfig": { "firebase": { "uri": "https://firebase.example.com", "serviceaccount": "/path/to/serviceAccountKey.json", "fcmkey": "AAAA...your_fcm_key" }, "apple": { "host": "api.push.apple.com", "pkcs8file": "/path/to/key.p8", "teamid": "TEAMID123", "keyid": "KEYID456", "appname": "com.example.app" }, "pushy": { "appSecret": "your_pushy_app_secret", "url": "https://api.pushy.me" } } } }, "GetServiceComponentsResponse": { "type": "object", "properties": { "name1": { "type": "string" }, "name2": { "type": "string" }, "name3": { "type": "string" } }, "example": { "name1": "https://xxx.xxxxxx.xxx/xxxxx", "name2": "https://xxx.xxxxxx.xxx/xxxxx", "name3": "https://xxx.xxxxxx.xxx/xxxxx" } }, "CreateSecretRequest": { "type": "object", "required": [ "tag", "value", "createdBy" ], "properties": { "tag": { "type": "string", "description": "Secret identifier. Must start with a letter [a-zA-Z] and contain only [a-zA-Z0-9_]", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "value": { "type": "string", "description": "Secret value to be encrypted and stored" }, "createdBy": { "type": "string", "description": "User or service that created the secret" } }, "example": { "tag": "stripe_api_key", "value": "sk_test_4eC39HqLyjWDarjtT1zdp7dc", "createdBy": "admin@example.com" } }, "CreateSecretResponse": { "type": "object", "properties": { "tag": { "type": "string", "description": "Secret identifier" }, "createdBy": { "type": "string", "description": "User or service that created the secret" }, "createdTs": { "type": "number", "description": "Unix timestamp in seconds" } }, "example": { "tag": "stripe_api_key", "createdBy": "admin@example.com", "createdTs": 1704067200 } }, "FetchSecretResponse": { "type": "object", "properties": { "tag": { "type": "string", "description": "Secret identifier" }, "value": { "type": "string", "description": "Decrypted secret value" }, "createdBy": { "type": "string", "description": "User or service that created the secret" }, "createdTs": { "type": "number", "description": "Unix timestamp in seconds" } }, "example": { "tag": "stripe_api_key", "value": "sk_test_4eC39HqLyjWDarjtT1zdp7dc", "createdBy": "admin@example.com", "createdTs": 1704067200 } }, "ListSecretsResponse": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Secret identifier" }, "createdBy": { "type": "string", "description": "User or service that created the secret" }, "createdTs": { "type": "number", "description": "Unix timestamp in seconds" }, "tenantId": { "type": "string", "description": "Tenant identifier" }, "communityId": { "type": "string", "description": "Community identifier" } } } } }, "example": { "secrets": [ { "tag": "stripe_api_key", "createdBy": "admin@example.com", "createdTs": 1704067200, "tenantId": "tenant_123", "communityId": "community_456" }, { "tag": "sendgrid_api_key", "createdBy": "admin@example.com", "createdTs": 1704067300, "tenantId": "tenant_123", "communityId": "community_456" } ] } }, "DeleteSecretResponse": { "type": "object", "properties": { "message": { "type": "string" } }, "example": { "message": "Secret deleted successfully" } }, "FetchSecretsRequest": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional array of secret tags to filter. If not provided, returns all secrets." } }, "example": { "tags": [ "stripe_api_key", "sendgrid_api_key" ] } }, "FetchSecretsResponse": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Secret identifier" }, "value": { "type": "string", "description": "Decrypted secret value" }, "createdBy": { "type": "string", "description": "User or service that created the secret" }, "createdTs": { "type": "number", "description": "Unix timestamp in seconds" }, "tenantId": { "type": "string", "description": "Tenant identifier" }, "communityId": { "type": "string", "description": "Community identifier" } } } } }, "example": { "secrets": [ { "tag": "stripe_api_key", "value": "sk_test_4eC39HqLyjWDarjtT1zdp7dc", "createdBy": "admin@example.com", "createdTs": 1704067200, "tenantId": "tenant_123", "communityId": "community_456" }, { "tag": "sendgrid_api_key", "value": "decrypted_value_here", "createdBy": "admin@example.com", "createdTs": 1704067300, "tenantId": "tenant_123", "communityId": "community_456" } ] } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "example": { "code": 400, "message": "Invalid secret tag: first character must be alphabetic and only [a-zA-Z0-9_] characters are allowed" } }, "ConsentResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "ECDSA encrypted consent data (or plain object when using swagger)", "properties": { "type": { "type": "string", "description": "Consent type", "example": "biometric" }, "title": { "type": "string", "description": "Consent document title", "example": "Biometric Information Consent Form" }, "subtitle": { "type": "string", "description": "Consent document subtitle", "example": "Please read carefully" }, "body": { "type": "string", "format": "byte", "description": "Base64-encoded HTML consent body" }, "acknowledgeText": { "type": "string", "description": "Acknowledgement text", "example": "I agree to the terms" }, "updatedAt": { "type": "number", "description": "Last update timestamp (epoch seconds)", "example": 1750012345 }, "updatedBy": { "type": "string", "description": "User who last updated the consent", "example": "admin@example.com" }, "docUpdatedAt": { "type": "number", "description": "Document content update timestamp (epoch seconds)", "example": 1750012345 }, "consentId": { "type": "string", "description": "IPFS hash of the current consent document", "example": "QmAbCdEf123456" }, "prevConsentId": { "type": "string", "description": "IPFS hash of the previous consent document version", "example": "QmPrEvIoUs789" }, "isEnabled": { "type": "boolean", "description": "Whether the consent is currently enabled", "example": true }, "version": { "type": "string", "description": "Version string derived from document timestamp", "example": "v1750012345000" } } }, "publicKey": { "type": "string", "description": "Service public key" } } }, "UpdateConsentRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "ECDSA encrypted consent data (or plain object when using swagger)", "properties": { "type": { "type": "string", "enum": [ "biometric" ], "example": "biometric" }, "isEnabled": { "type": "boolean", "example": true }, "title": { "type": "string", "example": "Biometric Data Processing Agreement" }, "body": { "type": "string", "format": "byte", "description": "Base64-encoded HTML consent body", "example": "PGgzPkJpb21ldHJpYyBDb25zZW50PC9oMz48cD5Db250ZW50Li4uPC9wPg==" }, "subtitle": { "type": "string", "example": "Please read carefully" }, "acknowledgeText": { "type": "string", "example": "I agree to the terms" }, "requestingUser": { "type": "string", "example": "admin@example.com" }, "eventData": { "type": "object", "description": "Audit event context passed through from the calling service. Contains the admin user's connection info for event logging. Optional \u2014 if omitted, audit events will not include user IP/agent.", "properties": { "user_id": { "type": "string", "description": "Admin user identifier", "example": "admin@example.com" }, "user_name": { "type": "string", "description": "Admin user display name", "example": "admin@example.com" }, "client_ip_address": { "type": "string", "description": "Admin user's IP address (from the originating client)", "example": "192.168.1.1" }, "caller_user_agent": { "type": "string", "description": "Admin user's browser user-agent (from the originating client)", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" } } } } } } }, "ActivateExtensionRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "ECDSA encrypted activation data (or plain object when using swagger)", "properties": { "extensionId": { "type": "string", "format": "uuid", "description": "Unique extension instance identifier (generated on first use)", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tenantDns": { "type": "string", "description": "1Kosmos tenant domain", "example": "customer.1kosmos.net" }, "communityName": { "type": "string", "description": "Community name within the tenant", "example": "default" }, "metadata": { "type": "object", "description": "Extension metadata for audit purposes", "properties": { "browser": { "type": "string", "example": "Chrome" }, "extensionVersion": { "type": "string", "example": "1.0.0" }, "userAgent": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" }, "language": { "type": "string", "example": "en-US" }, "timezone": { "type": "string", "example": "America/New_York" } } } } } }, "example": { "data": { "extensionId": "550e8400-e29b-41d4-a716-446655440000", "tenantDns": "customer.1kosmos.net", "communityName": "default", "metadata": { "browser": "Chrome", "extensionVersion": "1.0.0" } } } }, "ActivateExtensionResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "ECDSA encrypted response (or plain object when using swagger)", "properties": { "status": { "type": "string", "enum": [ "active" ], "example": "active" }, "extensionId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "activatedAt": { "type": "string", "format": "date-time", "example": "2026-05-13T10:30:45.000Z" } } }, "publicKey": { "type": "string", "description": "Service public key" } } }, "ExtensionStatusRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "ECDSA encrypted request data (or plain object when using swagger)", "properties": { "extensionId": { "type": "string", "format": "uuid", "description": "Extension instance identifier to check", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tenantDns": { "type": "string", "description": "1Kosmos tenant domain", "example": "customer.1kosmos.net" }, "communityName": { "type": "string", "description": "Community name within the tenant", "example": "default" } } } }, "example": { "data": { "extensionId": "550e8400-e29b-41d4-a716-446655440000", "tenantDns": "customer.1kosmos.net", "communityName": "default" } } }, "ExtensionStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "ECDSA encrypted response (or plain object when using swagger)", "properties": { "extensionId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "status": { "type": "string", "enum": [ "active", "deactivated", "unknown" ], "description": "Extension activation status", "example": "active" }, "activatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-05-13T10:30:45.000Z" }, "deactivatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": null } } }, "publicKey": { "type": "string", "description": "Service public key" } } }, "DeactivateExtensionRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "ECDSA encrypted request data (or plain object when using swagger)", "properties": { "extensionId": { "type": "string", "format": "uuid", "description": "Extension instance identifier to deactivate", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tenantDns": { "type": "string", "description": "1Kosmos tenant domain", "example": "customer.1kosmos.net" }, "communityName": { "type": "string", "description": "Community name within the tenant", "example": "default" }, "deactivatedBy": { "type": "string", "description": "Admin user or system that initiated deactivation", "example": "admin@company.com" } } } }, "example": { "data": { "extensionId": "550e8400-e29b-41d4-a716-446655440000", "tenantDns": "customer.1kosmos.net", "communityName": "default", "deactivatedBy": "admin@company.com" } } }, "DeactivateExtensionResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "ECDSA encrypted response (or plain object when using swagger)", "properties": { "extensionId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "status": { "type": "string", "enum": [ "deactivated" ], "example": "deactivated" }, "deactivatedAt": { "type": "string", "format": "date-time", "example": "2026-05-14T08:15:30.000Z" } } }, "publicKey": { "type": "string", "description": "Service public key" } } } }, "securitySchemes": { "keyId": { "type": "apiKey", "name": "keyId", "in": "header", "description": "ECDSA Public Key" }, "keySecret": { "type": "apiKey", "name": "keySecret", "in": "header", "description": "ECDSA Private Key" }, "license": { "type": "apiKey", "name": "license", "in": "header", "description": "License key from License API" }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "OAuth2 Bearer token (e.g. from OIDC PKCE flow with extension:activate scope)" } } }, "tags": [ { "name": "Secret Store", "description": "Secure storage and management of secrets (API keys, tokens, credentials)" }, { "name": "Public Key" }, { "name": "Healthz" }, { "name": "Extension", "description": "Browser extension activation and lifecycle management" }, { "name": "Environment" }, { "name": "ECDSA Helper" } ], "servers": [ { "url": "https://pilot-root.1kosmos.net/caas/" } ] }