{ "openapi": "3.1.1", "info": { "title": "Neostore internal API", "version": "v1" }, "servers": [ { "url": "https://app.neostore.cloud", "description": "Production Server" }, { "url": "https://app-qa.neostore.cloud", "description": "Staging Server" } ], "paths": { "/api/{tenantId}/barcode/{type}/{data}": { "get": { "tags": [ "Barcode" ], "summary": "Generate a barcode image", "description": "Generates a barcode or QR code image in PNG format with customizable colors and dimensions.\n\n## Supported Barcode Types\n- **QR Code**: 2D matrix barcode with error correction\n- **PDF417**: High-capacity 2D stacked barcode\n- **UPC-A/UPC-E**: Universal Product Code for retail\n- **EAN-8/EAN-13**: European Article Number for retail\n- **Code 39/93/128**: Linear barcodes for various applications\n- **ITF-14**: Interleaved 2 of 5 for shipping containers\n\n## Color Parameters\n- Colors must be specified as 6-digit hex values (without #)\n- Example: `fg=000000` for black, `bg=FFFFFF` for white\n\n## Dimensions\n- For QR codes: width acts as a sizing hint (height is ignored)\n- For linear barcodes: both width and height are applied\n\n## Caching\nGenerated images are cached for 100 days based on query parameters.", "parameters": [ { "name": "data", "in": "path", "description": "Data to encode.", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "description": "Barcode symbology to generate.", "required": true, "schema": { "default": "CODE128", "$ref": "#/components/schemas/BarcodeType" } }, { "name": "fg", "in": "query", "description": "Foreground color as HTML hex without the leading #.", "schema": { "type": "string", "default": "000000" } }, { "name": "bg", "in": "query", "description": "Background color as HTML hex without the leading #.", "schema": { "type": "string", "default": "FFFFFF" } }, { "name": "w", "in": "query", "description": "Target image width; for QR, acts as a hint.", "schema": { "type": "integer", "format": "int32", "default": 300 } }, { "name": "h", "in": "query", "description": "Image height; ignored for QR.", "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/{tenantId}/cache": { "delete": { "tags": [ "Cache" ], "summary": "Clear all cached data for the tenant", "description": "Removes all cached entries for the current tenant from the distributed cache system (FusionCache).\n\n## Use Cases\n- Force refresh of configuration changes\n- Clear stale data after external updates\n- Troubleshoot caching issues\n- Reset state during development/testing\n\n## Authorization\nRequires `Cache.Write` scope permission.\n\n## Impact\n- Subsequent requests will regenerate cached data\n- May cause temporary performance degradation\n- Only affects the specified tenant's cache", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cache cleared successfully for the tenant." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/customer": { "get": { "tags": [ "Customer" ], "summary": "Get authenticated customer profile", "description": "Retrieves comprehensive customer information by validating and enriching the authentication token claims.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authenticated customer profile returned.", "content": { "text/plain": { "schema": { "type": "object", "additionalProperties": { } } }, "application/json": { "schema": { "type": "object", "additionalProperties": { } } }, "text/json": { "schema": { "type": "object", "additionalProperties": { } } } } }, "401": { "description": "Caller not authenticated as customer.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "neo-customer": [ null ] } ] }, "post": { "tags": [ "Customer" ], "summary": "Create or update a customer account", "description": "Creates a new customer account or updates an existing one with provided information.\nSupports optional flow execution (e.g., preregistration) and multi-factor authentication challenges.\n\n## Account Modification\n- Creates account if customer does not exist\n- Updates existing customer data\n- Validates and enriches account data (e.g., deriving location from postal code)\n- Fills missing fields with defaults or derived values\n\n## Flow Execution\nWhen a flow name is specified:\n1. Account is created/updated\n2. Named flow is executed (e.g., \"preregistration\", \"activation\")\n3. Additional security challenges may be issued\n\nWhen flow is omitted:\n1. Account data is validated\n2. Fields are enriched and filled\n3. No additional processing occurs\n\n## Authorization\nNo explicit authorization required; customer context derived from account identifier.", "parameters": [ { "name": "flow", "in": "query", "description": "Optional flow name to execute after account creation (e.g., \"preregistration\"). When empty, data is validated and filled without additional processing", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Customer account payload with contact, identity, and profile data", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { } } }, "text/json": { "schema": { "type": "object", "additionalProperties": { } } }, "application/*+json": { "schema": { "type": "object", "additionalProperties": { } } } } }, "responses": { "200": { "description": "Account created or updated.", "content": { "text/plain": { "schema": { "type": "object", "additionalProperties": { } } }, "application/json": { "schema": { "type": "object", "additionalProperties": { } } }, "text/json": { "schema": { "type": "object", "additionalProperties": { } } } } }, "202": { "description": "Challenge issued for additional verification." }, "401": { "description": "Caller not authorized to create or update the account.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "412": { "description": "Validation failed for provided account data.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/customer/authenticate": { "post": { "tags": [ "Customer" ], "summary": "Authenticate customer and generate JWT token", "description": "Authenticates a customer using a specified identity provider and returns a JWT token for subsequent API calls.\n\n## Supported Providers\n- **Social Login**: Facebook, Apple, Google, Line, etc.\n- **One-Time Password (OTP)**: SMS, email, or other delivery methods\n- **Custom Providers**: Tenant-specific authentication mechanisms\n\n## Authentication Flow\n1. Client sends provider name and provider-specific authentication data\n2. System validates credentials with the specified provider\n3. Provider returns claims (identity attributes)\n4. System generates JWT token with 24-hour validity\n5. Token includes provider identifier for auditing\n\n## Token Usage\nThe returned JWT token should be included in subsequent API requests using the `Authorization: Bearer ` header.", "parameters": [ { "name": "provider", "in": "query", "description": "Provider used to authenticate the user.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Required data for the specified provider", "content": { "application/json": { "schema": { } }, "text/json": { "schema": { } }, "application/*+json": { "schema": { } } } }, "responses": { "200": { "description": "Authentication succeeded and token returned.", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "text/json": { "schema": { "type": "string" } } } }, "400": { "description": "Request is missing provider or contains malformed data.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "422": { "description": "Invalid authentication data for the specified provider.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/devices": { "get": { "tags": [ "Devices" ], "summary": "Get all registered devices", "description": "Returns all devices associated with the tenant, including their configuration and status.\n\n## Authorization\nRequires `Device.Read` scope.\n\n## Pagination\nCurrently returns all devices. Pagination may be added in future versions if needed.\n\n## Use Cases\n- Device inventory management\n- Configuration deployment\n- Status monitoring", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of all devices", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Device metadata exposed by the API.", "$ref": "#/components/schemas/Device" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Device metadata exposed by the API.", "$ref": "#/components/schemas/Device" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Device metadata exposed by the API.", "$ref": "#/components/schemas/Device" } } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while listing devices" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Devices" ], "summary": "Create a new device of the specified type.", "description": "Creates a new device with the specified type and configuration. Currently supports CrewCheck device type with logo URL configuration.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Device type and description.", "content": { "application/json": { "schema": { "description": "Payload to create a new device.", "$ref": "#/components/schemas/CreateDevice" } }, "text/json": { "schema": { "description": "Payload to create a new device.", "$ref": "#/components/schemas/CreateDevice" } }, "application/*+json": { "schema": { "description": "Payload to create a new device.", "$ref": "#/components/schemas/CreateDevice" } } } }, "responses": { "201": { "description": "Device created successfully" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while creating device" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/devices/{deviceId}": { "delete": { "tags": [ "Devices" ], "summary": "Delete a device and revoke its API key.", "description": "Removes the device from the system and invalidates any associated API keys. This prevents the device from authenticating to the system.", "parameters": [ { "name": "deviceId", "in": "path", "description": "Device identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Device deletion accepted" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while deleting device" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Devices" ], "summary": "Retrieve a device by id.", "description": "Returns detailed information about a specific device including its type and configuration settings.", "operationId": "Get", "parameters": [ { "name": "deviceId", "in": "path", "description": "Device identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Device details" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Device not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving device" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Devices" ], "summary": "Update a device.", "description": "Updates name, description, and enabled status.", "parameters": [ { "name": "deviceId", "in": "path", "description": "Device identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Update payload.", "content": { "application/json": { "schema": { "description": "Payload to update a device.", "$ref": "#/components/schemas/UpdateDevice" } }, "text/json": { "schema": { "description": "Payload to update a device.", "$ref": "#/components/schemas/UpdateDevice" } }, "application/*+json": { "schema": { "description": "Payload to update a device.", "$ref": "#/components/schemas/UpdateDevice" } } } }, "responses": { "200": { "description": "Device updated successfully" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Device not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while updating device" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/devices/{deviceId}/connect": { "post": { "tags": [ "Devices" ], "summary": "Connect a device using its API key and return device settings.", "description": "Establishes a connection for the device and returns its current configuration settings. This endpoint verifies the device's authorization before allowing the connection.", "parameters": [ { "name": "deviceId", "in": "path", "description": "Device identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection established with device settings", "content": { "text/plain": { "schema": { "description": "Connect result information", "$ref": "#/components/schemas/ConnectResponse" } }, "application/json": { "schema": { "description": "Connect result information", "$ref": "#/components/schemas/ConnectResponse" } }, "text/json": { "schema": { "description": "Connect result information", "$ref": "#/components/schemas/ConnectResponse" } } } }, "400": { "description": "Device is disabled", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized or invalid credentials", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Device not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while connecting device" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/devices/{deviceId}/connections/reset": { "post": { "tags": [ "Devices" ], "summary": "Reset a device connection and return a fresh API key and environment details.", "description": "Generates a new API key for the device and returns connection details including the environment URI. This is useful when the device needs to reconnect or its credentials have been compromised.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Tenant identifier.", "required": true, "schema": { "type": "string" } }, { "name": "deviceId", "in": "path", "description": "Device identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection token with new API key", "content": { "text/plain": { "schema": { "description": "Connection token information returned to the device.", "$ref": "#/components/schemas/ConnectionToken" } }, "application/json": { "schema": { "description": "Connection token information returned to the device.", "$ref": "#/components/schemas/ConnectionToken" } }, "text/json": { "schema": { "description": "Connection token information returned to the device.", "$ref": "#/components/schemas/ConnectionToken" } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while resetting device connection" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/emails/verify": { "post": { "tags": [ "EmailVerifier" ], "summary": "Validate email address format and domain", "description": "Performs comprehensive email validation to ensure addresses are deliverable and meet quality standards.\n\n## Validation Checks\n- **Syntax**: RFC 5322 compliance (format, special characters, structure)\n- **Domain Rules**: Optional tenant-specific restrictions:\n - Disposable email provider blocking\n - Corporate domain requirements\n - Whitelist/blacklist enforcement\n\n## Use Cases\n- Form validation during registration\n- Pre-send email verification\n- Data quality enforcement\n- Fraud prevention", "parameters": [ { "name": "email", "in": "query", "description": "Email address to validate.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Validation result returned", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EmailVerificationResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationResult" } } } }, "400": { "description": "Invalid email payload or format", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while validating email" } } } }, "/api/{tenantId}/insights/query": { "post": { "tags": [ "Insights" ], "summary": "Execute analytics query", "description": "Runs a custom analytics query and returns results in tabular format.\n\n## Authorization\nRequires `Insights.Read` scope.\n\n## Rate Limiting\nLimited to 60 requests per interval to protect analytics infrastructure.\n\n## Query Language\nTypically uses Kusto Query Language (KQL) syntax:\n```kql\nPasses\n| where timestamp > ago(7d)\n| summarize count() by passType\n| order by count_ desc\n```\n\n## Parameters\nSupports parameterized queries for security and reusability:\n```json\n{\n \"query\": \"Events | where Name == name | take 100\",\n \"parameters\": { \"name\": \"Pass:Installed\" }\n}\n```\n## Use Cases\n- Custom dashboards\n- Business intelligence reports\n- Data exports\n- Trend analysis\n\n## Performance\n- Query timeout: Configurable per tenant\n- Result limits: May be enforced\n- Caching: Not automatic - implement client-side if needed", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The query text, parameters, and optional execution settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "responses": { "200": { "description": "Query executed successfully", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/QueryResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "400": { "description": "Invalid query syntax or parameters", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while executing query" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes": { "get": { "tags": [ "Pass" ], "summary": "Retrieve passes with optional filtering, sorting, and pagination.", "description": "**Authorization:** Requires `Pass.Read` scope.\n\n**Filtering:** By identifiers (e.g., `identifiers.email`), metadata fields (e.g., `metadata.loyaltyTier`), pass type, or installation status (apple, google).\n\n**Sorting:** By id, passType, creationDate, lastUpdateDate, apple, google, or any identifier/metadata field.\n\n**Pagination:** Zero-based `pageIndex` and `pageSize`. Total count in `x-pagination-total` header.\n\n**Use Cases:** Search passes by customer attributes; monitor installation status; filter by loyalty tier or campaign flag.\n\n**Example — list loyalty passes, page 0:**\n```\nGET /api/{tenantId}/passes?pageIndex=0&pageSize=20\n &filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty\n &sortBy[0].field=creationDate&sortBy[0].direction=DESC\n```\n**Example — passes installed on Apple Wallet:**\n```\nGET /api/{tenantId}/passes?filter[0].field=installationStatus&filter[0].operator=contains&filter[0].value=apple\n```", "parameters": [ { "name": "pageIndex", "in": "query", "description": "Zero-based page index.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "pageSize", "in": "query", "description": "Number of passes per page.", "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "filter", "in": "query", "description": "Optional filters applied to identifiers, metadata, pass type, or installation status.", "schema": { "type": "array", "items": { "description": "Filter specification for pass queries.", "$ref": "#/components/schemas/FilterModel" } } }, { "name": "sortBy", "in": "query", "description": "Optional sort descriptors. When absent, results are unordered.", "schema": { "type": "array", "items": { "description": "Sort specification for pass queries.", "$ref": "#/components/schemas/SortModel" } } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paged list of passes returned successfully.", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Represents a pass returned by the API.", "$ref": "#/components/schemas/Pass" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Represents a pass returned by the API.", "$ref": "#/components/schemas/Pass" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Represents a pass returned by the API.", "$ref": "#/components/schemas/Pass" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "patch": { "tags": [ "Pass" ], "summary": "Update a pass and optionally its type.", "description": "**Authorization:** Requires `Pass.Write` scope.\n\n**Identification:** Use internal `id` (e.g., `id=Ed34kg3oA47`) or external identifiers with `id.` prefix (e.g., `id.y2.customerId=1233332`). Multiple identifiers must match exactly one pass.\n\n**Data:** Merged with existing data. Empty/null removes fields; omitted fields unchanged.\n\n**Metadata:** Set `options.UpdateMetadata=true` for recomputation (slower). Set `options.BypassQueue=true` for synchronous updates instead of queueing.\n\n**Type:** Optionally convert pass to different type.\n\n**Use Cases:** Update identifiers/metadata; push notifications; type conversion; bulk updates; urgent changes.\n\n**Example — update by platform pass ID:**\n```\nPATCH /api/{tenantId}/passes?id=xK9mP2nQr7sT\n \n{\n \"additionalData\": { \"loyaltyTier\": \"gold\" },\n \"options\": { \"updateMetadata\": true }\n}\n```\n**Example — update by external identifier:**\n```\nPATCH /api/{tenantId}/passes?id.shopify.customerId=12345\n \n{\n \"identifiers\": { \"email\": \"user@example.com\" },\n \"additionalData\": { \"loyaltyTier\": \"gold\" },\n \"options\": { \"updateMetadata\": false }\n}\n```", "parameters": [ { "name": "identifiers", "in": "query", "description": "identifier of the pass. To update a pass with a Wallet Crew internal id only specify `id` (example : `\"id\": \"Ed34kg3oA47\"`) to update a pass with external identifier prefix the key with `id.` (example : `\"id.y2.customerId\": \"1233332\"`) \n\nWhen multiple external identifiers is submitted all identifiers should be found. \nIf more than one pass is found an exception will be thrown.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "passType", "in": "query", "description": "type of the pass to update. type name should be one of the file in the `server/passes/` tenant configuration.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "data related to this pass. This data will be merge with the existing data.", "content": { "application/json": { "schema": { "description": "Data payload for single pass update operations.", "$ref": "#/components/schemas/SingleUpdatePassData" } }, "text/json": { "schema": { "description": "Data payload for single pass update operations.", "$ref": "#/components/schemas/SingleUpdatePassData" } }, "application/*+json": { "schema": { "description": "Data payload for single pass update operations.", "$ref": "#/components/schemas/SingleUpdatePassData" } } } }, "responses": { "200": { "description": "Pass update enqueued or applied successfully." }, "404": { "description": "No pass found matching the provided identifiers.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Pass" ], "summary": "Create a new pass.", "description": "**Authorization:** Requires `Pass.Write` scope OR valid identifier validation (HMAC signature, secret, or allowlisted unsigned).\n\n**Security:** Each identifier must validate via: (1) HMAC (key.hmac), (2) registered secret (key.secret), (3) security allowlist, or (4) Pass.Write scope. Omit identifiers if JWT contains customer claims.\n\n**Pass Type:** Template to use. Must match file in tenant `server/passes/` config.\n\n**Use Cases:** API-based pass creation; customer self-service with HMAC; bulk imports.\n\n**Example — create with HMAC-signed identifier:**\n```\nPOST /api/{tenantId}/passes?passType=loyalty\n \n{\n \"identifiers\": {\n \"shopify.customerId\": \"12345\",\n \"shopify.customerId.hmac\": \"{hmac-of-12345}\"\n },\n \"additionalData\": { \"loyaltyTier\": \"silver\" }\n}\n```\n**Example — create with Pass.Write scope (no HMAC required):**\n```\nPOST /api/{tenantId}/passes?passType=loyalty\n \n{\n \"identifiers\": { \"shopify.customerId\": \"12345\" },\n \"additionalData\": { \"loyaltyTier\": \"silver\" }\n}\n```", "parameters": [ { "name": "passType", "in": "query", "description": "Type of the pass to create. Must match a file in the tenant `server/passes/` configuration.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Data related to this pass.", "content": { "application/json": { "schema": { "description": "Data payload for pass creation operations.", "$ref": "#/components/schemas/CreatePassData" } }, "text/json": { "schema": { "description": "Data payload for pass creation operations.", "$ref": "#/components/schemas/CreatePassData" } }, "application/*+json": { "schema": { "description": "Data payload for pass creation operations.", "$ref": "#/components/schemas/CreatePassData" } } } }, "responses": { "200": { "description": "Pass created successfully.", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "text/json": { "schema": { "type": "string" } } } }, "401": { "description": "Identifiers cannot be validated and caller lacks Pass.Write scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/{passId}": { "get": { "tags": [ "Pass" ], "summary": "Retrieve the specified pass for the specified device.", "description": "Download an Apple Wallet pass:\n```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT?device=apple\n```\nAuto-redirect to the appropriate wallet based on user-agent:\n```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT?device=auto\n```\nTrack the installation source (email campaign, email medium):\n```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT?device=apple&neo.src=email-campaign|email\n```", "parameters": [ { "name": "passId", "in": "path", "description": "Platform-assigned pass identifier (random alphanumeric string, e.g. `xK9mP2nQr7sT`).", "required": true, "schema": { "pattern": "^[\\w-]{5,50}$", "type": "string" } }, { "name": "device", "in": "query", "description": "Target platform: `apple`, `google`, `preview`, or `auto`.", "schema": { "type": "string" } }, { "name": "Tags", "in": "query", "description": "Source tags for categorizing installation source.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Medium", "in": "query", "description": "Installation medium (e.g., email, sms, app).", "schema": { "type": "string" } }, { "name": "Origin", "in": "query", "description": "Installation origin or referrer.", "schema": { "type": "string" } }, { "name": "UserAgent", "in": "query", "description": "User agent string from the installation request.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "Pass" ], "summary": "Update a pass using its passId.", "description": "**Authorization:** Requires `Pass.Write` scope.\n\n**Identification:** Uses the pass's unique `passId` directly.\n\n**Data:** Merged with existing data. Empty/null removes fields; omitted fields unchanged.\n\n**Metadata:** Set `options.UpdateMetadata=true` for recomputation (slower). Set `options.BypassQueue=true` for synchronous updates instead of queueing.\n\n**Type:** Optionally convert pass to different type.\n\n**Use Cases:** Update passes by internal ID; push notifications; type conversion; urgent changes.\n\n**Example — update metadata and push notification:**\n```\nPATCH /api/{tenantId}/passes/xK9mP2nQr7sT\n \n{\n \"additionalData\": { \"loyaltyTier\": \"platinum\", \"points\": 5000 },\n \"options\": { \"updateMetadata\": true, \"bypassQueue\": false }\n}\n```\n**Example — urgent update, bypass queue:**\n```\nPATCH /api/{tenantId}/passes/xK9mP2nQr7sT\n \n{\n \"additionalData\": { \"boardingStatus\": \"boarding\" },\n \"options\": { \"updateMetadata\": true, \"bypassQueue\": true }\n}\n```", "parameters": [ { "name": "passId", "in": "path", "description": "The unique identifier of the pass to update.", "required": true, "schema": { "pattern": "^[\\w-]{5,50}$", "type": "string" } }, { "name": "passType", "in": "query", "description": "Optional type of the pass to update. Type name should match a file in the `server/passes/` tenant configuration.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Data payload containing identifiers, additional data, and update options.", "content": { "application/json": { "schema": { "description": "Data payload for single pass update operations.", "$ref": "#/components/schemas/SingleUpdatePassData" } }, "text/json": { "schema": { "description": "Data payload for single pass update operations.", "$ref": "#/components/schemas/SingleUpdatePassData" } }, "application/*+json": { "schema": { "description": "Data payload for single pass update operations.", "$ref": "#/components/schemas/SingleUpdatePassData" } } } }, "responses": { "200": { "description": "Pass update queued or completed successfully." }, "404": { "description": "Pass with the specified passId not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/{passId}/connect": { "get": { "tags": [ "Pass" ], "summary": "Retrieve a WebSocket URL for pass-level notifications.", "description": "```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT/connect\n \n```", "parameters": [ { "name": "passId", "in": "path", "description": "Platform-assigned pass identifier (random alphanumeric string, e.g. `xK9mP2nQr7sT`).", "required": true, "schema": { "pattern": "^[\\w-]{5,50}$", "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "WebSocket URL returned successfully.", "content": { "text/plain": { "schema": { "description": "Represents a Web PubSub connection response for a pass.", "$ref": "#/components/schemas/PassConnectResponse" } }, "application/json": { "schema": { "description": "Represents a Web PubSub connection response for a pass.", "$ref": "#/components/schemas/PassConnectResponse" } }, "text/json": { "schema": { "description": "Represents a Web PubSub connection response for a pass.", "$ref": "#/components/schemas/PassConnectResponse" } } } }, "404": { "description": "Pass not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } } } }, "/api/{tenantId}/passes/{passId}/data": { "get": { "tags": [ "Pass" ], "summary": "Retrieve aggregated pass data from all registered data providers.", "description": "```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT/data\n \n```", "parameters": [ { "name": "passId", "in": "path", "description": "Platform-assigned pass identifier (random alphanumeric string, e.g. `xK9mP2nQr7sT`).", "required": true, "schema": { "pattern": "^[\\w-]{5,50}$", "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/{tenantId}/passes/{passId}/data/raw": { "get": { "tags": [ "Pass" ], "summary": "Retrieve the raw persisted pass document for diagnostics.", "description": "```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT/data/raw\n \n```", "parameters": [ { "name": "passId", "in": "path", "description": "Platform-assigned pass identifier (random alphanumeric string, e.g. `xK9mP2nQr7sT`).", "required": true, "schema": { "pattern": "^[\\w-]{5,50}$", "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw pass document returned." } } } }, "/api/{tenantId}/passes/{passId}/notification": { "put": { "tags": [ "Pass" ], "summary": "Send a notification to the pass identified by its pass identifier", "parameters": [ { "name": "passId", "in": "path", "description": "The internal identifier of the pass", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The notification content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotifyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/NotifyRequest" } } } }, "responses": { "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "OK" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/{passId}/privileges": { "get": { "tags": [ "Privilege" ], "summary": "List privileges for the specified pass id.", "description": "Retrieves all privileges for a specific pass using its identifier.\nConvenience endpoint when the pass ID is already known.\n\n## Authorization\nRequires `Pass.Read` scope.\n\n## Sorting\nPrivileges are returned in priority order (highest to lowest).", "parameters": [ { "name": "passId", "in": "path", "description": "Pass id.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privileges returned", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Privilege" ], "summary": "Create a privilege for the specified pass id.", "description": "Creates a new privilege using the pass identifier directly. Use the PUT variants with a\nprivilegeId in the route for idempotent upsert semantics.\nThis is a convenience endpoint for scenarios where the pass ID is already known.\n\n## Authorization\nRequires `Pass.Write` scope.\n\n## Behavior\nSame as the identifiers-based variant but uses a path parameter instead of query identifiers.", "parameters": [ { "name": "passId", "in": "path", "description": "Pass id.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Privilege payload to create.", "content": { "application/json": { "schema": { "description": "Request model to create a new privilege.", "$ref": "#/components/schemas/InsertPrivilegeRequest" } }, "text/json": { "schema": { "description": "Request model to create a new privilege.", "$ref": "#/components/schemas/InsertPrivilegeRequest" } }, "application/*+json": { "schema": { "description": "Request model to create a new privilege.", "$ref": "#/components/schemas/InsertPrivilegeRequest" } } } }, "responses": { "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privilege queued" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/{passId}/privileges/{privilegeId}": { "delete": { "tags": [ "Privilege" ], "summary": "Delete a privilege for a specific pass.", "description": "Removes a privilege from a specific pass.\nBoth the pass and privilege must exist.\n\n## Authorization\nRequires `Pass.Write` scope.\n\n## Scope\nThis operation only affects the privilege with the specified pass.", "parameters": [ { "name": "passId", "in": "path", "description": "Pass identifier.", "required": true, "schema": { "type": "string" } }, { "name": "privilegeId", "in": "path", "description": "Privilege identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Pass or privilege not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "204": { "description": "Privilege deleted" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Privilege" ], "summary": "Retrieve a privilege for a specific pass.", "description": "Fetches a single privilege belonging to a specific pass.\nEnsures both the pass and privilege exist and are correctly associated.\n\n## Authorization\nRequires `Pass.Read` scope.\n\n## Validation\nReturns 404 if either the pass or the privilege is missing,\nor if the privilege does not belong to the specified pass.", "parameters": [ { "name": "passId", "in": "path", "description": "Pass identifier.", "required": true, "schema": { "type": "string" } }, { "name": "privilegeId", "in": "path", "description": "Privilege identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Pass or privilege not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privilege returned", "content": { "text/plain": { "schema": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } }, "application/json": { "schema": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } }, "text/json": { "schema": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Privilege" ], "summary": "Upsert (idempotent) a privilege for the specified pass id.", "description": "Creates or updates a privilege with the specified `privilegeId` for the given pass.\nThis endpoint is idempotent: repeated calls with the same payload produce the same result.", "parameters": [ { "name": "passId", "in": "path", "description": "Pass id.", "required": true, "schema": { "type": "string" } }, { "name": "privilegeId", "in": "path", "description": "Unique identifier of the privilege to upsert.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Privilege payload to upsert.", "content": { "application/json": { "schema": { "description": "Request model to patch an existing privilege.", "$ref": "#/components/schemas/PatchPrivilegeRequest" } }, "text/json": { "schema": { "description": "Request model to patch an existing privilege.", "$ref": "#/components/schemas/PatchPrivilegeRequest" } }, "application/*+json": { "schema": { "description": "Request model to patch an existing privilege.", "$ref": "#/components/schemas/PatchPrivilegeRequest" } } } }, "responses": { "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privilege upsert queued or applied" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/{passId}/view": { "get": { "tags": [ "Pass" ], "summary": "Redirect to a web page that lets the user view and download the pass.", "description": "```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT/view\n \n```\n Additional query parameters are forwarded to the view page.", "parameters": [ { "name": "passId", "in": "path", "description": "Platform-assigned pass identifier (random alphanumeric string, e.g. `xK9mP2nQr7sT`).", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "302": { "description": "Found" } } } }, "/api/{tenantId}/passes/{passIds}": { "get": { "tags": [ "Pass" ], "summary": "Retrieve multiple passes for the specified device.", "description": "Download a bundle of Apple Wallet passes:\n```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT,a3Bc4dEf5gHi?device=apple\n```\nRetrieve JSON for Google Wallet:\n```\nGET /api/{tenantId}/passes/xK9mP2nQr7sT,a3Bc4dEf5gHi?device=google\n```", "parameters": [ { "name": "passIds", "in": "path", "description": "Comma-separated serial numbers of the passes.", "required": true, "schema": { "pattern": "^[\\w-]{5,50},([\\w-]{5,50},?)+$", "type": "array", "items": { "type": "string" }, "description": "Collection of pass identifiers with parsing support." } }, { "name": "device", "in": "query", "description": "Target platform: `apple` or `google`.", "schema": { "type": "string" } }, { "name": "Tags", "in": "query", "description": "Source tags for categorizing installation source.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Medium", "in": "query", "description": "Installation medium (e.g., email, sms, app).", "schema": { "type": "string" } }, { "name": "Origin", "in": "query", "description": "Installation origin or referrer.", "schema": { "type": "string" } }, { "name": "UserAgent", "in": "query", "description": "User agent string from the installation request.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/{tenantId}/passes/findPass": { "get": { "tags": [ "Pass" ], "summary": "Retrieve a Wallet Crew passId from external identifiers.", "description": "Lookup with HMAC-signed identifier:\n```\nGET /api/{tenantId}/passes/findPass?shopify.customerId=12345&shopify.customerId.hmac={hmac}\n```\nLookup with Pass.Read scope (no HMAC required):\n```\nGET /api/{tenantId}/passes/findPass?shopify.customerId=12345\n```", "parameters": [ { "name": "identifiers", "in": "query", "description": "- When `{key}` is supplied, either provide `{key}.hmac` signed with a tenant secret, ensure `security.yml` allows unsigned identifiers, or authenticate with a Pass.Read scope (API key or JWT).\n- Authenticated user claims are also considered when present.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "passType", "in": "query", "description": "Optional pass type to restrict the search.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "text/json": { "schema": { "type": "string" } } } }, "204": { "description": "No Content" } } } }, "/api/{tenantId}/passes/findPasses": { "get": { "tags": [ "Pass" ], "summary": "Retrieve passes by direct pass IDs or via a registered supplier.", "description": "**Two Modes:**\n- **Direct Mode:** Pass `ids=id1,id2` to look up passes by serial number.\n- **Supplier Mode:** Pass `ids.{provider}={key}` (e.g. `ids.shopify=ORDER-12345`) to resolve pass IDs via a registered Neo.Runtime.Wallet.IPassSupplier. Missing passes are created automatically.\n Optionally sign the lookup with `ids.{provider}.hmac={hmac}` or `ids.{provider}.secret={secret}`.\n\n**Preview:** When `includePreview=true`, each item includes title, subtitle, colors, header text, and enabled status.\n\n**Use Cases:** E-commerce (order → passes); subscriptions (subscription → passes); mobile preview data; loyalty programs (member → passes).\n\n**Example — direct pass IDs lookup:**\n```\nGET /api/{tenantId}/passes/findPasses?ids=xK9mP2nQr7sT,a3Bc4dEf5gHi\n```\n**Example — resolve via supplier:**\n```\nGET /api/{tenantId}/passes/findPasses?ids.shopify=ORDER-12345&includePreview=true\n```\n**Example — resolve via supplier with HMAC:**\n```\nGET /api/{tenantId}/passes/findPasses?ids.shopify=ORDER-12345&ids.shopify.hmac={hmac}\n```", "parameters": [ { "name": "identifiers", "in": "query", "description": "Query parameters used to identify passes.\nUse `ids={csv}` for direct lookup, or `ids.{provider}={key}` for supplier-based lookup.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "includePreview", "in": "query", "description": "When true, include preview details (title, subtitle, colors, header text, enabled status) for each pass.", "schema": { "type": "boolean", "default": false } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pass list retrieved successfully.", "content": { "text/plain": { "schema": { "type": "array", "items": { } } }, "application/json": { "schema": { "type": "array", "items": { } } }, "text/json": { "schema": { "type": "array", "items": { } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } } } }, "/api/{tenantId}/passes/notification": { "put": { "tags": [ "Pass" ], "summary": "Send a notification to the corresponding pass", "parameters": [ { "name": "identifiers", "in": "query", "description": "identifier of the pass. To update a pass with a neostore internal id only specify `id` (example : `\"id\": \"Ed34kg3oA47\"`) to update a pass with external identifier prefix the key with `id.` (example : `\"id.y2.customerId\": \"1233332\"`) \n\nWhen multiple external identifiers is submitted all identifiers should be found. \nIf more than one pass is found an exception will be thrown.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The notification content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotifyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/NotifyRequest" } } } }, "responses": { "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "OK" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/privileges": { "get": { "tags": [ "Privilege" ], "summary": "List privileges for the pass resolved from identifiers.", "description": "Retrieves all privileges associated with a pass using query identifiers.\nPrivileges are sorted by priority (highest first) and movements within each privilege are ordered by date (oldest first).\n\n## Authorization\nRequires `Pass.Read` scope.\n\n## Use Cases\n- Display available offers and benefits to the pass holder\n- Check current loyalty balance or punch card progress\n- Verify privilege availability before redemption", "parameters": [ { "name": "identifiers", "in": "query", "description": "Pass identifiers (internal or external) used to resolve the pass.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privileges returned", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Privilege" ], "summary": "Create a privilege for the pass identified by the supplied identifiers.", "description": "Creates a new privilege for the specified pass. Use the PUT variants with a\nprivilegeId in the route for idempotent upsert semantics.\nPrivileges represent benefits, offers, or entitlements tied to a pass.\n\n## Authorization\nRequires `Pass.Write` scope.\n\n## Operation\nWhen a privilege is applied, the system queues it for processing.\nOptional notification can be sent to the pass holder upon application.\n\n## Use Cases\n- Adding loyalty points or rewards\n- Issuing promotional offers\n- Granting membership benefits", "parameters": [ { "name": "identifiers", "in": "query", "description": "Pass identifiers (internal or external) used to resolve the pass.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Privilege payload to create.", "content": { "application/json": { "schema": { "description": "Request model to create a new privilege.", "$ref": "#/components/schemas/InsertPrivilegeRequest" } }, "text/json": { "schema": { "description": "Request model to create a new privilege.", "$ref": "#/components/schemas/InsertPrivilegeRequest" } }, "application/*+json": { "schema": { "description": "Request model to create a new privilege.", "$ref": "#/components/schemas/InsertPrivilegeRequest" } } } }, "responses": { "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privilege queued" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/privileges/{privilegeId}": { "delete": { "tags": [ "Privilege" ], "summary": "Delete a privilege by its id.", "description": "Removes a privilege from the system entirely.\nThe privilege is deleted across all passes it may be associated with.\n\n## Authorization\nRequires `Pass.Write` scope.\n\n## Irreversibility\nThis operation is permanent. The privilege cannot be recovered after deletion.", "parameters": [ { "name": "privilegeId", "in": "path", "description": "Privilege identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Privilege not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "204": { "description": "Privilege deleted" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Privilege" ], "summary": "Retrieve a privilege by its id.", "description": "Fetches detailed information about a specific privilege across all passes in the tenant.\nReturns complete privilege metadata including content, appearance, and current state.\n\n## Authorization\nRequires `Pass.Read` scope.\n\n## Use Cases\n- View privilege details for display or validation\n- Check privilege expiration or availability status\n- Retrieve localized content for multiple languages", "parameters": [ { "name": "privilegeId", "in": "path", "description": "Privilege identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Privilege not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privilege returned", "content": { "text/plain": { "schema": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } }, "application/json": { "schema": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } }, "text/json": { "schema": { "description": "Represents a persisted privilege with a required unique identifier.", "$ref": "#/components/schemas/Privilege" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Privilege" ], "summary": "Upsert (idempotent) a privilege for the pass identified by the supplied identifiers.", "description": "Creates or updates a privilege with the specified `privilegeId` for the resolved pass.\nThis endpoint is idempotent: repeated calls with the same payload produce the same result.", "parameters": [ { "name": "identifiers", "in": "query", "description": "Pass identifiers (internal or external) used to resolve the pass.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "privilegeId", "in": "path", "description": "Unique identifier of the privilege to upsert.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Privilege payload to upsert.", "content": { "application/json": { "schema": { "description": "Request model to patch an existing privilege.", "$ref": "#/components/schemas/PatchPrivilegeRequest" } }, "text/json": { "schema": { "description": "Request model to patch an existing privilege.", "$ref": "#/components/schemas/PatchPrivilegeRequest" } }, "application/*+json": { "schema": { "description": "Request model to patch an existing privilege.", "$ref": "#/components/schemas/PatchPrivilegeRequest" } } } }, "responses": { "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Privilege upsert queued or applied" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/privileges/{privilegeId}/movements": { "post": { "tags": [ "Privilege" ], "summary": "Apply a movement (transaction) to a privilege's value and return the created movement identifier.", "description": "Records a change to a privilege's value (redemption, adjustment, issuance).\nMovements are tracked in the privilege's history for audit purposes and form the basis for computing current value.\n\n## Authorization\nRequires `Pass.Write` scope.\n\n## Concurrency Control\nThe `OldValue` parameter enables optimistic locking with server-side validation.\nThe handler compares the expected value (OldValue) to the current sum with epsilon tolerance (±0.0001).\nThis prevents race conditions when multiple clients attempt simultaneous updates.\nIf values differ beyond tolerance, returns 409 Conflict; if privilege is missing, returns 404 Not Found.\n\n## Use Cases\n- Redeeming points or stamps (negative movement)\n- Issuing or adjusting loyalty balance (positive movement)\n- Applying promotional adjustments", "parameters": [ { "name": "privilegeId", "in": "path", "description": "Privilege identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Movement request with concurrency check.", "content": { "application/json": { "schema": { "description": "Request model to apply a movement (transaction) to a privilege's value.", "$ref": "#/components/schemas/ApplyMovementRequest" } }, "text/json": { "schema": { "description": "Request model to apply a movement (transaction) to a privilege's value.", "$ref": "#/components/schemas/ApplyMovementRequest" } }, "application/*+json": { "schema": { "description": "Request model to apply a movement (transaction) to a privilege's value.", "$ref": "#/components/schemas/ApplyMovementRequest" } } } }, "responses": { "404": { "description": "Privilege not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "400": { "description": "MovementValue is zero", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "409": { "description": "Current value does not match OldValue (concurrency conflict)", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "200": { "description": "Movement applied successfully", "content": { "text/plain": { "schema": { "description": "Response payload after a movement is created.", "$ref": "#/components/schemas/MovementResponse" } }, "application/json": { "schema": { "description": "Response payload after a movement is created.", "$ref": "#/components/schemas/MovementResponse" } }, "text/json": { "schema": { "description": "Response payload after a movement is created.", "$ref": "#/components/schemas/MovementResponse" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/pushUpdate": { "post": { "tags": [ "Pass" ], "summary": "Push update for passes matching the filter.", "description": "**Authorization:** Requires `Pass.Write` scope.\n\n**Filtering:** Same as GetPasses�identifiers, metadata, pass type, installation status.\n\n**Async:** Updates are queued. 200 response means scheduled, not complete. Monitor via statistics endpoint.\n\n**Data Merge:** Merged into each matching pass. Set `UpdateMetadata=true` for recomputation (slower). Adjust `Throughput` for concurrency.\n\n**Bulk Operations:** Ideal for campaigns, loyalty updates, seasonal offers. Use `CorrelationId` for tracking.\n\n**Use Cases:** Campaign push; loyalty tier changes; offer refresh; bulk metadata updates.\n\n**Example — push a seasonal offer to all loyalty passes:**\n```\nPOST /api/{tenantId}/passes/pushUpdate\n ?filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty\n \n{\n \"additionalData\": { \"offer\": \"summer2025\", \"discount\": \"20%\" },\n \"options\": {\n \"updateMetadata\": true,\n \"throughput\": 12,\n \"correlationId\": \"campaign-summer-2025\"\n }\n}\n```", "parameters": [ { "name": "filter", "in": "query", "description": "Optional filters applied to select passes.", "schema": { "type": "array", "items": { "description": "Filter specification for pass queries.", "$ref": "#/components/schemas/FilterModel" } } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Data to merge into each pass and options controlling metadata refresh and throughput.", "content": { "application/json": { "schema": { "description": "Data payload for multi-pass (bulk) update operations.", "$ref": "#/components/schemas/MultipleUpdatePassData" } }, "text/json": { "schema": { "description": "Data payload for multi-pass (bulk) update operations.", "$ref": "#/components/schemas/MultipleUpdatePassData" } }, "application/*+json": { "schema": { "description": "Data payload for multi-pass (bulk) update operations.", "$ref": "#/components/schemas/MultipleUpdatePassData" } } } }, "responses": { "200": { "description": "Passes scheduled for update; returns the count in the response body.", "content": { "text/plain": { "schema": { "description": "Result returned after scheduling a bulk push update operation.", "$ref": "#/components/schemas/PushUpdateResult" } }, "application/json": { "schema": { "description": "Result returned after scheduling a bulk push update operation.", "$ref": "#/components/schemas/PushUpdateResult" } }, "text/json": { "schema": { "description": "Result returned after scheduling a bulk push update operation.", "$ref": "#/components/schemas/PushUpdateResult" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/pushUpdate/{correlationId}/cancel": { "post": { "tags": [ "Pass" ], "summary": "Cancel a running push update operation.", "description": "**Authorization:** Requires `Pass.Read` scope.\n\n**Cancellation:** Marks operation for cancellation. May take time if updates already dispatched.\n\n**Correlation Id:** Use the id from push update schedule or statistics.\n\n**Use Cases:** Stop campaign on config error; cancel nightly batch; prevent updates on security issue.\n\n**Example:**\n```\nPOST /api/{tenantId}/passes/pushUpdate/campaign-summer-2025/cancel\n```", "parameters": [ { "name": "correlationId", "in": "path", "description": "CorrelationId used when scheduling the push update.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cancellation request accepted." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/pushUpdate/status": { "get": { "tags": [ "Pass" ], "summary": "Retrieve execution statistics for recent push update operations.", "description": "**Authorization:** Requires `Pass.Read` scope.\n\n**Statistics:** Operation id, correlationId, start/last activity, pass count, completed count, error count, Apple/Google deployment counts, cancellation status.\n\n**Ordering:** Sorted descending by start date (most recent first).\n\n**Use Cases:** Monitor batch progress; track campaign deployment; identify failures; audit history.\n\n**Example:**\n```\nGET /api/{tenantId}/passes/pushUpdate/status\n```", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Statistics retrieved successfully.", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Aggregated status of a push update operation.", "$ref": "#/components/schemas/PushUpdateStatistics" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Aggregated status of a push update operation.", "$ref": "#/components/schemas/PushUpdateStatistics" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Aggregated status of a push update operation.", "$ref": "#/components/schemas/PushUpdateStatistics" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/stats": { "get": { "tags": [ "Pass" ], "summary": "Get pass distribution statistics", "description": "Returns aggregated counts of passes by installation status and platform.\n\n## Authorization\nRequires `Pass.Read` scope.\n\n## Metrics Explained\n- **Total**: All passes created (regardless of installation)\n- **Active**: Passes currently installed on at least one device\n- **Apple**: Passes installed on Apple Wallet\n- **Google**: Passes installed on Google Wallet\n\n## Filtering\nOptional `passType` parameter filters statistics to a specific pass type (e.g., \"loyalty\", \"coupon\").\n\n## Performance Note\nThis endpoint queries all passes and may be slow for large datasets. For production dashboards, consider using the Insights API with pre-aggregated queries.", "parameters": [ { "name": "passType", "in": "query", "description": "Optional pass type filter (must match a tenant pass configuration file).", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "description": "Get statistics about pass usage", "$ref": "#/components/schemas/PassStatistic" } }, "application/json": { "schema": { "description": "Get statistics about pass usage", "$ref": "#/components/schemas/PassStatistic" } }, "text/json": { "schema": { "description": "Get statistics about pass usage", "$ref": "#/components/schemas/PassStatistic" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/receipts/{token}/pdf": { "get": { "tags": [ "Receipt" ], "summary": "Download receipt as PDF", "description": "Retrieves a transaction receipt in PDF format using a secure signed token.\n\n## Token-Based Security\nThe token is a JWT containing:\n- **receiptProvider**: Source system identifier (e.g., \"cegid\", \"shopify\")\n- **receiptNumber**: Transaction/receipt identifier\n- **storeId**: Optional store context\n\n## Receipt Providers\nSystem supports multiple providers:\n- POS system integrations\n- E-commerce platforms\n- Custom receipt generators\n\n## Token Generation\nTokens must be generated server-side using the security token generator with appropriate claims.\n\n## Use Cases\n- Email receipt links\n- Customer portal receipt downloads\n- Embedded receipts in passes\n- Order history displays\n\n## Security\n- Tokens are time-limited and signed\n- Cannot be forged or tampered with\n- Single-use recommended for sensitive transactions", "parameters": [ { "name": "token", "in": "path", "description": "JWT containing receiptProvider, receiptNumber, and optional storeId claims.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Receipt PDF returned", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } }, "text/json": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid or malformed token", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Receipt number missing or not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while generating receipt" } } } }, "/api/{tenantId}/redirect": { "get": { "tags": [ "Redirect" ], "summary": "List all the redirection associated to this tenant", "description": "Returns all configured redirects for the tenant (both active and expired) as an async enumerable stream.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of all redirection", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebRedirectEntity" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebRedirectEntity" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebRedirectEntity" } } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while listing redirects" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Redirect" ], "summary": "Create a new redirect", "description": "Creates a new redirect with the specified layout, parameters, and optional configuration (expiration date, label, URL length).", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The redirection link to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateModel" } } } }, "responses": { "201": { "description": "Returns the newly created item", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while creating redirect" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/redirect/{id}": { "delete": { "tags": [ "Redirect" ], "summary": "Delete the requested redirection", "description": "Removes the redirect from the system and returns the deleted entity for confirmation.", "parameters": [ { "name": "id", "in": "path", "description": "Identifier of the redirection to delete", "required": true, "schema": { "minLength": 3, "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "When the object has been successfully deleted", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "204": { "description": "if the item to delete has not been found" }, "500": { "description": "Internal server error while deleting redirect" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Redirect" ], "summary": "Get detail of a specific redirection", "description": "Retrieves full details of a redirect including its layout, parameters, and configuration options.", "parameters": [ { "name": "id", "in": "path", "description": "id of the redirection", "required": true, "schema": { "minLength": 3, "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "return the specified item", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "If the item does not exists", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving redirect" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Redirect" ], "summary": "Update a specific redirection. All properties will be overwritten by the new entity.", "description": "Replaces the entire redirect configuration (PUT operation). All properties must be provided.", "parameters": [ { "name": "id", "in": "path", "description": "Identifier of the redirection to update.", "required": true, "schema": { "minLength": 3, "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The redirection to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateModel" } } } }, "responses": { "201": { "description": "Returns the updated item", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebRedirectEntity" } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "204": { "description": "if the item to update has not been found" }, "500": { "description": "Internal server error while updating redirect" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/scans": { "post": { "tags": [ "Scan" ], "summary": "Record a pass barcode scan event", "description": "Records scan events when pass barcodes/QR codes are scanned. Scans are correlated to passes\nand generate scan completion events for downstream systems (redemption, attendance tracking, etc.).\n\n## Authorization\nRequires PassScan.Scan scope", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Scan payload containing raw barcode data and format type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddScanRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddScanRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AddScanRequest" } } } }, "responses": { "201": { "description": "Scan successfully recorded; pass identifier returned", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/AddScanResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AddScanResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddScanResponse" } } } }, "400": { "description": "Invalid scan request (data too short/long, missing type)", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized or invalid credentials", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "No pass found with matching scan data", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Processing error during scan event generation" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/scheduler/{taskId}/executions": { "get": { "tags": [ "Scheduler" ], "summary": "Get execution history for scheduled task", "description": "Returns recent execution history for a scheduled background task, including success/failure status and retry information.\n\n## Authorization\nRequires `Scheduler.History` scope.\n\n## Use Cases\n- Task monitoring dashboards\n- Failure investigation\n- Performance analysis\n- Retry pattern verification", "parameters": [ { "name": "taskId", "in": "path", "description": "Id of the scheduled task (as declared in scheduler.yml).", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution history retrieved successfully", "content": { "text/plain": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Execution" }, { "$ref": "#/components/schemas/ExecutionSummary" }, { "$ref": "#/components/schemas/ExecutionDetail" } ] } } }, "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Execution" }, { "$ref": "#/components/schemas/ExecutionSummary" }, { "$ref": "#/components/schemas/ExecutionDetail" } ] } } }, "text/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Execution" }, { "$ref": "#/components/schemas/ExecutionSummary" }, { "$ref": "#/components/schemas/ExecutionDetail" } ] } } } } }, "400": { "description": "Invalid taskId format", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving execution history" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/scheduler/{taskId}/executions/{executionId}": { "get": { "tags": [ "Scheduler" ], "summary": "Retrieve a specific scheduler execution with its associated logs.", "description": "Returns comprehensive execution details including all trace and dependency logs collected from Application Insights. Useful for debugging scheduled task issues and monitoring execution performance.", "parameters": [ { "name": "taskId", "in": "path", "description": "CorrelationId of the scheduled task.", "required": true, "schema": { "type": "string" } }, { "name": "executionId", "in": "path", "description": "Execution Id reported by Application Insights.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution details with logs retrieved successfully", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ExecutionDetail" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionDetail" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ExecutionDetail" } } } }, "400": { "description": "Invalid taskId or executionId format", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Execution not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving execution detail" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/scheduler/executions": { "get": { "tags": [ "Scheduler" ], "summary": "List recent scheduler executions for the tenant", "description": "Returns the most recent scheduler task executions across all configured tasks for the tenant.\nUseful to monitor scheduler health, spot failing tasks and drill into individual executions.\n \n**Sorting:** By `startDate`, `taskId`, `taskType`, `duration`, or `retryIndex`.\n \n**Pagination:** Zero-based `pageIndex` and `pageSize`. Total count in `x-pagination-total` header.\n \n## Authorization\nRequires `Scheduler.History` scope.", "parameters": [ { "name": "pageIndex", "in": "query", "description": "Zero-based page index.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "pageSize", "in": "query", "description": "Number of executions per page.", "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "sortBy", "in": "query", "description": "Optional sort descriptors. Defaults to startDate DESC.", "schema": { "type": "array", "items": { "description": "Sort specification for scheduler execution queries.", "$ref": "#/components/schemas/SchedulerSortModel" } } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution list retrieved successfully", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionSummary" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionSummary" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionSummary" } } } } }, "400": { "description": "Invalid query parameter", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving executions" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/secrets": { "get": { "tags": [ "Secret" ], "summary": "List all secret keys", "description": "Returns keys of all secrets stored for the tenant. Does not return values for security.\n\n## Authorization\nRequires `Secret.Read` scope.\n\n## Security Note\nOnly key names are returned, not the actual secret values. Use GET /{key} to retrieve individual secret values.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of all secret keys", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } }, "application/json": { "schema": { "type": "array", "items": { "type": "string" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving secrets" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/secrets/{key}": { "delete": { "tags": [ "Secret" ], "summary": "Delete a secret.", "description": "Removes a secret from the secret store. The secret key must contain only allowed characters. Once deleted, the secret cannot be retrieved.", "parameters": [ { "name": "key", "in": "path", "description": "Secret key (validated for allowed characters).", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Secret deleted successfully" }, "400": { "description": "Invalid secret key format", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while deleting secret" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Secret" ], "summary": "Retrieve secret value", "description": "Returns a secret value by key.\n\n## Authorization\nRequires `Secret.Read` scope.\n\n## Security Considerations\n- Values are transmitted over HTTPS only\n- Expired secrets return 404\n- Consider short-lived tokens for highly sensitive secrets", "parameters": [ { "name": "key", "in": "path", "description": "Secret key.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret value retrieved", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "text/json": { "schema": { "type": "string" } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Secret not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving secret" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Secret" ], "summary": "Create or update secret", "description": "Stores or replaces a secret value with optional validity period.\n\n**Authorization:** Requires `Secret.Write` scope.\n\n**Key Format:** Alphanumeric characters and hyphens only; case-sensitive.\n\n**Validity Period:** ExpiresOn and NotBefore are optional; omit both for permanent secrets. To rotate, create new secret with new key and delete old one after grace period.\n\n**Use Cases:** API keys, tokens, service credentials, encryption keys, third-party integration secrets.", "parameters": [ { "name": "key", "in": "path", "description": "Secret key (validated for allowed characters).", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Payload containing value and optional validity period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SetRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SetRequest" } } } }, "responses": { "204": { "description": "Secret created or updated successfully" }, "400": { "description": "Invalid secret key format", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while storing secret" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/stores": { "get": { "tags": [ "Store" ], "summary": "Get all stores accessible to the current user", "description": "Returns stores based on the caller's authorization level:\n\n## Administrator Access\nGlobal administrators see all stores in the tenant.\n\n## Limited Access\nRegular users see only stores they have `Stores.Read` permission for, as determined by:\n- JWT token claims\n- Tenant permission providers\n- Store-specific access controls\n## Use Cases\n- Store selector UI\n- Multi-location dashboards\n- Regional filtering", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stores returned based on caller authorization.", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/stores/{storeId}": { "get": { "tags": [ "Store" ], "summary": "Get detailed information for a specific store", "description": "Retrieves comprehensive store details including localized resources and custom properties.\n\n## Authorization\nRequires `Stores.Read` scope for the specified store.\n## Use Cases\n- Store detail pages\n- Location-based routing\n- Store-specific configuration", "parameters": [ { "name": "storeId", "in": "path", "description": "The store identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Store found and returned.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/Store" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Store" } }, "text/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized for the store.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Store not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/stores/{storeId}/additionalResources": { "get": { "tags": [ "Store" ], "summary": "Get localized resources for a store", "description": "Retrieves store-specific localized content from configured resource files.\n\n## Resource Structure\nResources are organized hierarchically:\n```yaml\nstores:\n store123:\n welcomeMessage: \"Welcome to our downtown location\"\n hours: \"Mon-Fri 9AM-9PM\"\n```\n\n## Localization\n- Resources vary by language/culture\n- Configured via `AdditionalLocaleFiles` in tenant settings\n- Falls back gracefully when translations are missing\n\n## Use Cases\n- Store-specific messaging\n- Location hours and contact info\n- Custom promotional content", "parameters": [ { "name": "storeId", "in": "path", "description": "The store identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Localized resources returned.", "content": { "text/plain": { "schema": { "type": "object", "additionalProperties": { } } }, "application/json": { "schema": { "type": "object", "additionalProperties": { } } }, "text/json": { "schema": { "type": "object", "additionalProperties": { } } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized for the store.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Store not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/stores/{storeId}/advisors": { "get": { "tags": [ "Store" ], "summary": "Get all staff advisors for a store", "description": "Returns the list of advisors (sales associates, staff members) assigned to a specific store location.\n\n## Authorization\nRequires `Stores.Read` scope for the specified store.\n## Use Cases\n- Staff selection in appointment booking\n- Associate assignment for customer service\n- Sales attribution and tracking\n- Employee directory", "parameters": [ { "name": "storeId", "in": "path", "description": "The store identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Advisors returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advisor" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advisor" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advisor" } } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized for the store.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Store not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/templates/render": { "post": { "tags": [ "Templates" ], "summary": "Render one or more Liquid templates with the provided context.", "description": "Applies the tenant-configured template engine to each submitted template using the\nshared context payload. All templates are rendered with a single engine instantiation.\n \nThe response is an array aligned with the request `Templates` array: `Results[i]` is the rendered output of `Templates[i]`.\n \n## Authorization\nRequires `Core.Read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "List of template strings and an optional shared rendering context.", "content": { "application/json": { "schema": { "description": "Request body for rendering Liquid templates.", "$ref": "#/components/schemas/RenderTemplateRequest" } }, "text/json": { "schema": { "description": "Request body for rendering Liquid templates.", "$ref": "#/components/schemas/RenderTemplateRequest" } }, "application/*+json": { "schema": { "description": "Request body for rendering Liquid templates.", "$ref": "#/components/schemas/RenderTemplateRequest" } } } }, "responses": { "200": { "description": "Templates rendered; check `errors` for per-template Liquid failures.", "content": { "text/plain": { "schema": { "description": "Response body returned by M:Neo.Web.Api.Template.Controllers.TemplatesController.Render(Neo.Web.Api.Template.Controllers.TemplatesController.RenderTemplateRequest,System.Threading.CancellationToken).", "$ref": "#/components/schemas/RenderTemplateResponse" } }, "application/json": { "schema": { "description": "Response body returned by M:Neo.Web.Api.Template.Controllers.TemplatesController.Render(Neo.Web.Api.Template.Controllers.TemplatesController.RenderTemplateRequest,System.Threading.CancellationToken).", "$ref": "#/components/schemas/RenderTemplateResponse" } }, "text/json": { "schema": { "description": "Response body returned by M:Neo.Web.Api.Template.Controllers.TemplatesController.Render(Neo.Web.Api.Template.Controllers.TemplatesController.RenderTemplateRequest,System.Threading.CancellationToken).", "$ref": "#/components/schemas/RenderTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "422": { "description": "A Liquid syntax error prevented rendering. Check `detail` for the Liquid error message.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/tokens/generate": { "post": { "tags": [ "Security" ], "summary": "Generate JWT tokens from custom claims", "description": "Creates one or more JWT tokens with custom claims for advanced authentication scenarios.\n\n## Use Cases\n- Testing and development\n- Service-to-service authentication\n- Custom identity workflows\n- Token migration scenarios\n\n## Authorization\nRequires AuthenticationToken.Write scope - restricted to authorized administrators and services.\n\n## Validity Duration\n- Default: 10 years (3650.00:00:00.000)\n- Configurable via query parameter in TimeSpan format\n- Examples: 1.00:00:00 (1 day), 30.00:00:00 (30 days)\n\n## Request Format\nAccepts an array of claim sets, where each set generates one token:\n[[{\\\"type\\\": \\\"sub\\\", \\\"value\\\": \\\"user123\\\"}, {\\\"type\\\": \\\"email\\\", \\\"value\\\": \\\"user@example.com\\\"}]]\n\n## Security Warning\nGenerated tokens have full authentication authority. Protect endpoint access and token distribution carefully.", "parameters": [ { "name": "validityDuration", "in": "query", "description": "Optional validity duration in TimeSpan format (e.g., \"1.00:00:00\" for 1 day). Default is 10 years", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Array of claim sets; each set generates one JWT token", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "array", "items": { "description": "Claim to generate JWT token for", "$ref": "#/components/schemas/WebClaim" } } } }, "text/json": { "schema": { "type": "array", "items": { "type": "array", "items": { "description": "Claim to generate JWT token for", "$ref": "#/components/schemas/WebClaim" } } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "array", "items": { "description": "Claim to generate JWT token for", "$ref": "#/components/schemas/WebClaim" } } } } } }, "responses": { "200": { "description": "Tokens generated successfully.", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } }, "application/json": { "schema": { "type": "array", "items": { "type": "string" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks AuthenticationToken.Write scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks": { "get": { "tags": [ "WebHook" ], "summary": "Get all configured webhooks", "description": "Returns all webhook subscriptions configured for the tenant.\n\n## Authorization\nRequires `Webhook.Read` scope.\n## Event Patterns\nSupports wildcards:\n- `customer.*` - All customer events\n- `pass.created` - Specific event\n- `*` - All events (use with caution)\n\n## Use Cases\n- Webhook management UI\n- Configuration audit\n- Integration documentation", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhooks returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookWithId" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookWithId" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookWithId" } } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks Webhook.Read scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "WebHook" ], "summary": "Create a new webhook subscription", "description": "Registers a new webhook endpoint to receive event notifications.\n\n## Authorization\nRequires `Webhook.Write` scope.\n\n## Automatic Generation\n- **ID**: 5-character random identifier (automatically assigned)\n- **SignatureSecret**: 64-character secret (automatically generated)\n\n## Request Signing\nWhen sending webhook events, the platform adds an `X-NEOSTORE-SIGNATURE` header containing HMAC-SHA256 signature:\n```\nHMAC-SHA256(requestBody, signatureSecret)\n```\n\n## Endpoint Requirements\n- Must accept POST requests\n- Should respond within 30 seconds\n- Should return 2xx status code for success\n- Must use HTTPS in production\n\n## Event Wildcards\n- `pass.*` - All pass events\n- `customer.created` - Specific event\n- `store.*.updated` - Pattern matching", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The webhook to create", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebHook" }, { "$ref": "#/components/schemas/WebHookWithId" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebHook" }, { "$ref": "#/components/schemas/WebHookWithId" } ] } }, "application/*+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebHook" }, { "$ref": "#/components/schemas/WebHookWithId" } ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebHookWithId" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebHookWithId" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebHookWithId" } } } }, "201": { "description": "Webhook created." }, "400": { "description": "Invalid webhook payload.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks Webhook.Write scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/{id}": { "delete": { "tags": [ "WebHook" ], "summary": "Delete a webhook subscription", "description": "Permanently removes a webhook. The endpoint will no longer receive event notifications.\n\n## Authorization\nRequires `Webhook.Write` scope.\n\n## Behavior\n- Webhook is immediately removed from configuration\n- No further events will be sent to the endpoint\n- Action cannot be undone (must recreate webhook if needed)", "parameters": [ { "name": "id", "in": "path", "description": "Identifier of the webhook", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted." }, "404": { "description": "Webhook not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks Webhook.Write scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "WebHook" ], "summary": "Get a specific webhook by ID", "description": "Retrieves detailed information about a single webhook subscription.\n\n## Authorization\nRequires `Webhook.Read` scope.\n\n## Security Note\nThe signature secret is sensitive. Store it securely and never expose it in client-side code.", "parameters": [ { "name": "id", "in": "path", "description": "Identifier of the webhook", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook returned.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebHookWithId" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebHookWithId" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebHookWithId" } } } }, "404": { "description": "Webhook not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks Webhook.Read scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "WebHook" ], "summary": "Update an existing webhook", "description": "Modifies webhook configuration while preserving ID and signature secret.\n\n## Authorization\nRequires `Webhook.Write` scope.\n\n## Updatable Fields\n- Description\n- Events (array of event patterns)\n- Endpoint URL\n- Enabled status\n\n## Preserved Fields\n- ID (immutable)\n- SignatureSecret (immutable - use same secret for request validation)\n\n## Use Cases\n- Change event subscriptions\n- Update endpoint URL\n- Enable/disable webhook temporarily\n- Modify description", "parameters": [ { "name": "id", "in": "path", "description": "Identifier of the webhook", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "new Webhook information", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebHook" }, { "$ref": "#/components/schemas/WebHookWithId" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebHook" }, { "$ref": "#/components/schemas/WebHookWithId" } ] } }, "application/*+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebHook" }, { "$ref": "#/components/schemas/WebHookWithId" } ] } } }, "required": true }, "responses": { "200": { "description": "Webhook updated." }, "404": { "description": "Webhook not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "400": { "description": "Invalid webhook payload.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks Webhook.Write scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/tenants": { "get": { "tags": [ "Tenant" ], "summary": "List tenant directory entries with status and purpose.", "description": "**Authorization:** Global Administrator role required.\n\n**Pagination:** If results exceed max page size, `X-continuationToken` header contains token for next page.\n\n**Response Fields:** `tenantId`, `status`, `purpose`.\n\n**Use Cases:** Tenant directory; system-wide operations; migration tools; admin dashboards.", "responses": { "200": { "description": "Tenant directory entries returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantDirectoryEntry" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantDirectoryEntry" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantDirectoryEntry" } } } } }, "401": { "description": "Caller not authenticated as admin.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller is not a Global Administrator.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ null ] } ] } }, "/api/tenants/{tenantId}": { "delete": { "tags": [ "Tenant" ], "summary": "Delete tenant configuration files.", "description": "**Authorization:** Global Administrator role required.\n\n**Operation:** Removes all config files for tenant.\n\n**Use Cases:** Tenant deprovisioning; cleanup; environment removal.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tenant configuration deleted." }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized to delete tenant configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ null ] } ] }, "get": { "tags": [ "Tenant" ], "summary": "Download tenant configuration as ZIP archive.", "description": "**Authorization:** Requires `TenantConfiguration.Read` scope.\n\n**File Selection:** Omit `files` parameter for complete backup; specify files for partial backup.\n\n**Versioning:** Omit `datetime` for latest version; specify for point-in-time snapshot.\n\n**Archive Naming:** `{datetime}-{partial-}tenantId.fctwc` (e.g., `20240115-093045-mystore.fctwc` or `20240115-093045-partial-mystore.fctwc`).\n\n**Use Cases:** Backup, disaster recovery, configuration comparison, audit, environment synchronization.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "files", "in": "query", "description": "Get only a subset of configuration. Don't specify any file to get all the configuration", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "datetime", "in": "query", "description": "Date when to retrieve the configuration. If null or omitted, latest version would be returned", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Configuration archive returned." }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized to read tenant configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Tenant or specified files not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "patch": { "tags": [ "Tenant" ], "summary": "Partially update tenant configuration files.", "description": "**Authorization:** Requires `TenantConfiguration.Write` scope.\n\n**Partial Update:** Only included files updated/removed. Other files unchanged.\n\n**Empty Files:** Empty file in ZIP = removal from config.\n\n**Force:** Set `force=true` to save despite validation errors.\n\n**Use Cases:** Targeted config changes; single-file updates; incremental deployments.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "description": "force save even if there is any errors", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "A zip containing the files to modify. If a zip contains an empty file it will be removed from the configuration.", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "200": { "description": "Tenant configuration partially updated.", "content": { "text/plain": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } }, "application/json": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } }, "text/json": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } } } }, "400": { "description": "Invalid input payload.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized to write tenant configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Tenant not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Tenant" ], "summary": "Create or update tenant configuration files.", "description": "**Authorization:** Requires `TenantConfiguration.Write` scope.\n\n**Full Replacement:** All configured files overwritten. Missing files deleted.\n\n**Force:** Set `force=true` to save despite validation errors.\n\n**Input:** Multipart form with ZIP containing all config files.\n\n**Use Cases:** Full config deployment; environment promotion; disaster recovery restore.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "description": "force save even if there is any errors", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "A zip file containing all configuration file", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "200": { "description": "Tenant configuration created or updated.", "content": { "text/plain": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } }, "application/json": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } }, "text/json": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } } } }, "400": { "description": "Invalid input payload.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized to write tenant configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Tenant" ], "summary": "Create a new tenant with configuration files.", "description": "**Authorization:** Requires `TenantConfiguration.Write` scope.\n\n**Conflict:** Returns 409 if tenant already exists.\n\n**Force:** Set `force=true` to save despite validation errors (use with caution).\n\n**Use Cases:** New tenant provisioning; initial deployment; tenant migration.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "description": "force save even if there is any errors", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "A zip file containing all configuration file", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "200": { "description": "Tenant created with configuration.", "content": { "text/plain": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } }, "application/json": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } }, "text/json": { "schema": { "description": "Version information related to a tenant configuration", "$ref": "#/components/schemas/TenantConfigurationVersionInformation" } } } }, "400": { "description": "Invalid input payload.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized to write tenant configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "409": { "description": "Tenant already exists.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/tenants/{tenantId}/{layoutId}": { "get": { "tags": [ "Tenant" ], "summary": "Get merged configuration for a tenant layout.", "description": "**Merging:** Loads base configuration and merges with layout-specific settings. Layout settings take precedence. Applies registered configuration modifiers.\n\n**Layouts:** Different UI/UX configurations�web (desktop), mobile (native app), kiosk (in-store), pos (point-of-sale).\n\n**Use Cases:** App initialization; feature flags; themes; layout-specific rules.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "layoutId", "in": "path", "description": "Identifier of the layout", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Merged layout configuration returned.", "content": { "text/plain": { "schema": { } }, "application/json": { "schema": { } }, "text/json": { "schema": { } } } }, "404": { "description": "Tenant or layout configuration not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/tenants/{tenantId}/config/history": { "get": { "tags": [ "Tenant" ], "summary": "Get tenant configuration change history.", "description": "**Authorization:** Requires `TenantConfiguration.Read` scope.\n \n**Version Source:** Uses blob version history from `.version` to reconstruct configuration changes.\n \n**Filtering:** Use `files` (supports wildcard `*`) to keep only changes impacting specific files.\n \n**Pagination:** `offset` and `limit` support numeric pagination.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "files", "in": "query", "description": "Optional file filter. Supports wildcard (`*`).", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "offset", "in": "query", "description": "Number of history entries to skip.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of history entries to return.", "schema": { "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "History returned.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TenantConfigurationHistoryPage" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TenantConfigurationHistoryPage" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TenantConfigurationHistoryPage" } } } }, "400": { "description": "Invalid request parameters.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller not authorized to read tenant configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/tenants/{tenantId}/test": { "get": { "tags": [ "Tenant" ], "summary": "Validate tenant configuration.", "description": "**Validation:** YAML syntax, schemas, required fields, integration settings, resource references, business rule consistency.\n\n**Auth:** Optional admin auth. Unauthenticated get basic success/failure. Authenticated get detailed errors.\n\n**Use Cases:** Pre-deployment validation; troubleshooting; CI/CD checks; manual verification.", "parameters": [ { "name": "tenantId", "in": "path", "description": "Identifier of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration valid." }, "401": { "description": "Caller not authenticated (when admin auth enforced).", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Validation failed or unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/warmup": { "get": { "tags": [ "Warmup" ], "summary": "Preload all tenant configurations", "description": "Sequentially loads configuration for all tenants to populate caches and avoid cold-start delays.\n\n## Purpose\n- **Reduce First-Request Latency**: Pre-populates caches before real traffic arrives\n- **Prevent Request Pile-Up**: Avoids concurrent configuration loads during app startup\n- **Improve User Experience**: Ensures fast response times from the first request\n\n## Behavior\n- Acquires an exclusive lock to prevent concurrent warmup operations\n- Returns HTTP 425 (Too Early) if another warmup is already in progress\n- Processes each tenant sequentially (not in parallel)\n- Continues warmup even if individual tenants fail (logs errors)\n- Respects cancellation tokens for graceful shutdown\n\n## Typical Usage\nShould be called by:\n- Azure App Service warmup triggers\n- Kubernetes readiness probes\n- Deployment scripts\n- Health check systems\n\n## Performance Considerations\n- Duration depends on number of tenants\n- May take several seconds to minutes for large deployments\n- Does not block other API requests", "responses": { "200": { "description": "Warmup completed successfully." }, "425": { "description": "Another warmup operation is already in progress.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/admin/apiKeys": { "get": { "tags": [ "ApiKeys" ], "summary": "List API keys for the tenant", "description": "Returns all API key definitions stored in `security.yml`.\nKey hashes are never included in responses.\n \n## Authorization\nRequires `tenant.apiKey:read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API keys returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "oneOf": [ { "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed.", "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } } }, "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } } }, "text/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "ApiKeys" ], "summary": "Create a new API key", "description": "Generates a cryptographically secure token, stores its SHA-256 hash in `security.yml`,\nand returns the plaintext token in the response.\n**The token is only returned once — copy it immediately.**\n \n## Authorization\nRequires `tenant.apiKey:write` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request body to create an API key.", "$ref": "#/components/schemas/CreateApiKeyRequest" } }, "text/json": { "schema": { "description": "Request body to create an API key.", "$ref": "#/components/schemas/CreateApiKeyRequest" } }, "application/*+json": { "schema": { "description": "Request body to create an API key.", "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "API key created. Response includes the one-time plaintext token.", "content": { "text/plain": { "schema": { "description": "Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again.", "$ref": "#/components/schemas/ApiKeyCreatedResponse" } }, "application/json": { "schema": { "description": "Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again.", "$ref": "#/components/schemas/ApiKeyCreatedResponse" } }, "text/json": { "schema": { "description": "Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again.", "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "400": { "description": "Name is invalid or permissions are missing.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "409": { "description": "A key with this name already exists.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/apiKeys/{keyName}": { "delete": { "tags": [ "ApiKeys" ], "summary": "Delete an API key", "description": "Removes the API key entry from `security.yml`. The key immediately stops working.\n \n## Authorization\nRequires `tenant.apiKey:write` scope.", "parameters": [ { "name": "keyName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "API key deleted." }, "404": { "description": "API key not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "ApiKeys" ], "summary": "Get a specific API key", "description": "Returns the API key definition identified by keyName.\nThe key hash is never returned.\n \n## Authorization\nRequires `tenant.apiKey:read` scope.", "parameters": [ { "name": "keyName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key returned.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } } } }, "404": { "description": "API key not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "ApiKeys" ], "summary": "Update an API key", "description": "Replaces the `enabled` and `permissions` fields of the key.\nThe key name and the stored hash are not changed.\n \n## Authorization\nRequires `tenant.apiKey:write` scope.", "parameters": [ { "name": "keyName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request body to update an API key.", "$ref": "#/components/schemas/UpdateApiKeyRequest" } }, "text/json": { "schema": { "description": "Request body to update an API key.", "$ref": "#/components/schemas/UpdateApiKeyRequest" } }, "application/*+json": { "schema": { "description": "Request body to update an API key.", "$ref": "#/components/schemas/UpdateApiKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "API key updated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" }, { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } ], "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." } } } }, "400": { "description": "Permissions are missing.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "API key not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/config": { "get": { "tags": [ "Config" ], "summary": "Get tenant core configuration", "description": "Returns the tenant name, favicon URLs, effective public URI, enabled extensions, and tenant language settings.\n \n## Authorization\nRequires `tenant.core:read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration returned.", "content": { "text/plain": { "schema": { "description": "Tenant core configuration response", "$ref": "#/components/schemas/TenantConfigWeb" } }, "application/json": { "schema": { "description": "Tenant core configuration response", "$ref": "#/components/schemas/TenantConfigWeb" } }, "text/json": { "schema": { "description": "Tenant core configuration response", "$ref": "#/components/schemas/TenantConfigWeb" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "patch": { "tags": [ "Config" ], "summary": "Update tenant core configuration", "description": "Updates editable core fields in `config.yml`.\nStatus and purpose can only be modified by global administrators.\n \n## Authorization\nRequires `tenant.configuration.general:write` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Tenant core configuration patch request.", "$ref": "#/components/schemas/UpdateTenantConfigWebRequest" } }, "text/json": { "schema": { "description": "Tenant core configuration patch request.", "$ref": "#/components/schemas/UpdateTenantConfigWebRequest" } }, "application/*+json": { "schema": { "description": "Tenant core configuration patch request.", "$ref": "#/components/schemas/UpdateTenantConfigWebRequest" } } }, "required": true }, "responses": { "200": { "description": "Configuration updated and returned.", "content": { "text/plain": { "schema": { "description": "Tenant core configuration response", "$ref": "#/components/schemas/TenantConfigWeb" } }, "application/json": { "schema": { "description": "Tenant core configuration response", "$ref": "#/components/schemas/TenantConfigWeb" } }, "text/json": { "schema": { "description": "Tenant core configuration response", "$ref": "#/components/schemas/TenantConfigWeb" } } } }, "400": { "description": "Invalid language configuration.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Status or purpose update attempted without global-admin role.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/extensions/aparte": { "delete": { "tags": [ "AparteAdmin" ], "summary": "Delete Aparte configuration", "description": "Removes `server/aparte.yml` from tenant configuration and deletes the stored API key.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Configuration deleted." }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks required scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "AparteAdmin" ], "summary": "Get the Aparte configuration", "description": "Returns the non-secret Aparte configuration for this tenant and whether an API key is currently stored.\nReturns 404 when Aparte is not configured.\nThe API key itself is never returned.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration returned.", "content": { "text/plain": { "schema": { "description": "Response body for Aparte configuration.", "$ref": "#/components/schemas/AparteConfigurationResponse" } }, "application/json": { "schema": { "description": "Response body for Aparte configuration.", "$ref": "#/components/schemas/AparteConfigurationResponse" } }, "text/json": { "schema": { "description": "Response body for Aparte configuration.", "$ref": "#/components/schemas/AparteConfigurationResponse" } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks required scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Aparte is not configured for this tenant.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "AparteAdmin" ], "summary": "Set Aparte configuration", "description": "Validates credentials against the Aparte WalletCrew API, then saves the configuration to `server/aparte.yml`.\nOmit `apiKey` to update settings without rotating the secret (the existing stored key is used for the credential check).", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request body for setting Aparte configuration.", "$ref": "#/components/schemas/SetAparteRequest" } }, "text/json": { "schema": { "description": "Request body for setting Aparte configuration.", "$ref": "#/components/schemas/SetAparteRequest" } }, "application/*+json": { "schema": { "description": "Request body for setting Aparte configuration.", "$ref": "#/components/schemas/SetAparteRequest" } } }, "required": true }, "responses": { "204": { "description": "Configuration saved." }, "400": { "description": "Request body is invalid or the credentials failed to validate against the Aparte API.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks required scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/extensions/cloudflare/turnstile": { "delete": { "tags": [ "TurnstileAdmin" ], "summary": "Delete Cloudflare Turnstile configuration", "description": "Removes `server/cloudflare.yml` from tenant configuration.\nThis disables Turnstile for the tenant.\nAlso removes the Turnstile secret when present.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Configuration deleted." }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks required scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "TurnstileAdmin" ], "summary": "Get the Cloudflare Turnstile site key", "description": "Returns the public Turnstile site key configured for this tenant.\nReturns 404 when Turnstile is not configured.\nThe secret key is not returned for security reasons.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration returned.", "content": { "text/plain": { "schema": { "description": "Response body for Turnstile configuration.", "$ref": "#/components/schemas/TurnstileConfigurationResponse" } }, "application/json": { "schema": { "description": "Response body for Turnstile configuration.", "$ref": "#/components/schemas/TurnstileConfigurationResponse" } }, "text/json": { "schema": { "description": "Response body for Turnstile configuration.", "$ref": "#/components/schemas/TurnstileConfigurationResponse" } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks required scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Turnstile is not configured for this tenant.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "TurnstileAdmin" ], "summary": "Set Cloudflare Turnstile configuration", "description": "Saves the Turnstile site key to `server/cloudflare.yml`.\nOmit `secretKey` to update the site key without rotating the secret.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Turnstile configuration to apply.", "content": { "application/json": { "schema": { "description": "Request body for setting Turnstile configuration.", "$ref": "#/components/schemas/SetTurnstileRequest" } }, "text/json": { "schema": { "description": "Request body for setting Turnstile configuration.", "$ref": "#/components/schemas/SetTurnstileRequest" } }, "application/*+json": { "schema": { "description": "Request body for setting Turnstile configuration.", "$ref": "#/components/schemas/SetTurnstileRequest" } } }, "required": true }, "responses": { "204": { "description": "Configuration saved." }, "400": { "description": "Request body is invalid.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Caller not authenticated.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller lacks required scope.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/permissions": { "get": { "tags": [ "Permissions" ], "summary": "List available permissions and their descriptions", "description": "Returns permission areas and scope descriptions.\n \n## Authorization\nRequires `tenant.access:read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Permissions returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Web response for a permission area (category of scopes)", "$ref": "#/components/schemas/PermissionAreaWeb" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Web response for a permission area (category of scopes)", "$ref": "#/components/schemas/PermissionAreaWeb" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Web response for a permission area (category of scopes)", "$ref": "#/components/schemas/PermissionAreaWeb" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/roles": { "get": { "tags": [ "Roles" ], "summary": "List available roles and permissions for the tenant", "description": "Returns role definitions and associated permission.\n \n## Authorization\nRequires `tenant.access:read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Roles returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDefinition" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDefinition" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDefinition" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Roles" ], "summary": "Create a new role", "description": "Adds a new role entry to `security.yml`.\n \n## Authorization\nRequires `tenant.access.role:write` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request body to create a role.", "$ref": "#/components/schemas/CreateRoleRequest" } }, "text/json": { "schema": { "description": "Request body to create a role.", "$ref": "#/components/schemas/CreateRoleRequest" } }, "application/*+json": { "schema": { "description": "Request body to create a role.", "$ref": "#/components/schemas/CreateRoleRequest" } } }, "required": true }, "responses": { "201": { "description": "Role created.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } } } }, "400": { "description": "Name is invalid or permissions are missing.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "409": { "description": "A role with this name already exists, or the name is reserved.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/roles/{roleName}": { "delete": { "tags": [ "Roles" ], "summary": "Delete a role", "description": "Removes a role from `security.yml`.\nThe \"administrator\" role cannot be deleted.\n \n## Authorization\nRequires `tenant.access.role:write` scope.", "parameters": [ { "name": "roleName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Role deleted." }, "404": { "description": "Role not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "409": { "description": "The role is the immutable \"administrator\" role.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Roles" ], "summary": "Get a specific role and permissions for the tenant", "description": "Returns role definition and associated permissions for a single role.\n \n## Authorization\nRequires `tenant.access:read` scope, or the caller must have the same role as `roleName`.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "roleName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Role returned.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } } } }, "401": { "description": "Caller not authorized.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Role not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } } }, "put": { "tags": [ "Roles" ], "summary": "Update a role's permissions", "description": "Replaces the permission list of an existing role in `security.yml`.\nThe \"administrator\" role cannot be modified.\n \n## Authorization\nRequires `tenant.access.role:write` scope.", "parameters": [ { "name": "roleName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request body to update a role's permissions.", "$ref": "#/components/schemas/UpdateRoleRequest" } }, "text/json": { "schema": { "description": "Request body to update a role's permissions.", "$ref": "#/components/schemas/UpdateRoleRequest" } }, "application/*+json": { "schema": { "description": "Request body to update a role's permissions.", "$ref": "#/components/schemas/UpdateRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Role updated.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } } } }, "400": { "description": "Permissions are missing.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Role not found.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "409": { "description": "The role is the immutable \"administrator\" role.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/users": { "get": { "tags": [ "Users" ], "summary": "List all users attached to the tenant", "description": "Returns all back-office users with access to this tenant.\n \n## Authorization\nRequires `tenant.access:read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users returned.", "content": { "text/plain": { "schema": { "type": "array", "items": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } } }, "application/json": { "schema": { "type": "array", "items": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } } }, "text/json": { "schema": { "type": "array", "items": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Users" ], "summary": "Create a new user or attach an existing user to the tenant, unless already attached", "description": "Creates a new Auth0 user or attaches an existing one to this tenant. If the user already has access to the tenant (a valid role), returns HTTP 409 Conflict.\n \n## Authorization\nRequires `tenant.access:write` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request payload for creating a tenant user.", "$ref": "#/components/schemas/CreateTenantUserRequest" } }, "text/json": { "schema": { "description": "Request payload for creating a tenant user.", "$ref": "#/components/schemas/CreateTenantUserRequest" } }, "application/*+json": { "schema": { "description": "Request payload for creating a tenant user.", "$ref": "#/components/schemas/CreateTenantUserRequest" } } } }, "responses": { "201": { "description": "User created or attached.", "content": { "text/plain": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } }, "application/json": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } }, "text/json": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } } } }, "409": { "description": "User already has access to tenant.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/users/{userId}": { "delete": { "tags": [ "Users" ], "summary": "Remove a user from the tenant", "description": "Removes the tenant access from the user but keeps the Auth0 account.\n \n## Authorization\nRequires `tenant.access:write` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "User removed from tenant." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "get": { "tags": [ "Users" ], "summary": "Get a user attached to the tenant", "description": "Returns the back-office user details for the requested tenant.\n \n## Authorization\nRequires `tenant.access:read` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User returned.", "content": { "text/plain": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } }, "application/json": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } }, "text/json": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } } } }, "404": { "description": "User not found for tenant.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "put": { "tags": [ "Users" ], "summary": "Update a user attached to the tenant", "description": "Updates the tenant role and/or display name for a back-office user.\n \n## Authorization\nRequires `tenant.access:write` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request payload for updating a tenant user.", "$ref": "#/components/schemas/UpdateTenantUserRequest" } }, "text/json": { "schema": { "description": "Request payload for updating a tenant user.", "$ref": "#/components/schemas/UpdateTenantUserRequest" } }, "application/*+json": { "schema": { "description": "Request payload for updating a tenant user.", "$ref": "#/components/schemas/UpdateTenantUserRequest" } } } }, "responses": { "200": { "description": "User updated.", "content": { "text/plain": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } }, "application/json": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } }, "text/json": { "schema": { "description": "Tenant-scoped user representation.", "$ref": "#/components/schemas/TenantUser" } } } }, "404": { "description": "User not found for tenant.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/admin/users/me": { "get": { "tags": [ "Users" ], "summary": "Get current authenticated user for the tenant", "description": "Returns profile information and fully-expanded permissions for the current authenticated back-office user.\n \n- If caller is global administrator, all permissions are returned.\n- If role contains wildcard permissions (`*` or `area:*`), values are expanded.\n \n## Authorization\nRequires `tenant.core:read` scope.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current user returned.", "content": { "text/plain": { "schema": { "description": "Current authenticated tenant user representation.", "$ref": "#/components/schemas/CurrentTenantUser" } }, "application/json": { "schema": { "description": "Current authenticated tenant user representation.", "$ref": "#/components/schemas/CurrentTenantUser" } }, "text/json": { "schema": { "description": "Current authenticated tenant user representation.", "$ref": "#/components/schemas/CurrentTenantUser" } } } }, "401": { "description": "Caller identity is missing user identifier.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "User does not have access to this tenant.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/cachedContent/{key}": { "get": { "tags": [ "CachedContent" ], "summary": "Retrieve cached binary content", "description": "Fetches pre-generated or cached binary content by key with automatic MIME type detection.\n\n## Caching Strategy\n- **Cache Duration**: 100 days (client and CDN)\n- **Optimal for**: Images, PDFs, generated reports, static assets\n- **MIME Type**: Automatically detected from file extension or stored metadata\n\n## Key Structure\nKeys can use nested paths:\n- `reports/monthly-2024-01.pdf`\n- `images/products/item-123.jpg`\n- `generated/invoice-456.pdf`\n\n## Use Cases\n- Dynamically generated images (charts, QR codes)\n- Report caching\n- Optimized asset delivery\n- Pre-rendered content\n\n## Performance\nContent is served directly from blob storage with aggressive caching headers to minimize server load.", "parameters": [ { "name": "key", "in": "path", "description": "Blob key (supports nested path).", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary content returned" }, "404": { "description": "Content not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving cached content" } } } }, "/api/{tenantId}/cegid/sandbox": { "get": { "tags": [ "Cegid" ], "summary": "Retrieve Cegid receipt/ticket data", "description": "Sandbox endpoint to retrieve receipt data from Cegid Y2 for testing and development.\nReturns raw JSON receipt structure for pass generation validation.\n\n## Authorization\nRequires TenantConfigurationAccessControlled authorization", "operationId": "Cegid-Sandbox", "parameters": [ { "name": "key", "in": "query", "description": "Receipt composite key in the form stump-number (e.g., ABC-1234).", "required": true, "schema": { "pattern": "(?.*)-(?\\d+)", "type": "string" } }, { "name": "externalReference", "in": "query", "description": "External reference of the receipt used when key is not provided.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Receipt data returned", "content": { "text/plain": { "schema": { } }, "application/json": { "schema": { } }, "text/json": { "schema": { } } } }, "400": { "description": "Invalid receipt identifier", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Receipt not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving receipt" } } } }, "/api/{tenantId}/cegid/sandbox/attachReceiptToCustomer": { "post": { "tags": [ "Cegid" ], "summary": "Simulate Cegid Y2 customer registration", "description": "Test endpoint for customer registration workflow validation without connecting to production Cegid Y2.\nSimulates customer data creation and retrieval flows for sandbox testing.\n\n## Use Cases\n- Validate customer registration form data\n- Test receipt generation workflows\n- Debug data transformation logic\n- Verify webhook processing\n\n## Authorization\nRequires TenantConfigurationAccessControlled authorization", "parameters": [ { "name": "key", "in": "query", "description": "Receipt composite key in the form stump-number (e.g., ABC-1234).", "required": true, "schema": { "pattern": "(?.*)-(?\\d+)", "type": "string" } }, { "name": "externalReference", "in": "query", "description": "External reference of the receipt used when key is not provided.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Payload containing at least email and optional first/last names.", "content": { "application/json": { "schema": { } }, "text/json": { "schema": { } }, "application/*+json": { "schema": { } } } }, "responses": { "200": { "description": "Customer linked to receipt successfully", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "text/json": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input payload or receipt identifier", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while attaching receipt" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/cegid/settings/civilities": { "get": { "tags": [ "Cegid" ], "summary": "List Cegid civilities (titles)", "description": "Retrieves available civility titles (Mr., Mrs., Dr., Prof., etc.) from Cegid Y2 system.\nCivilities are localized based on configured language and used in customer registration.\n\n## Civility Types\nCommon civilities include:\n- Mr. (M., Monsieur, Herr, etc.)\n- Mrs. (Mme., Madame, Frau, etc.)\n- Ms. (Mlle., Mademoiselle, Fräulein, etc.)\n- Dr., Prof., Dr.-Ing., and other professional titles\n\n## Use Cases\n- Populate civility dropdown in registration forms\n- Support culturally appropriate title selection\n- Enable localized customer communication\n\n## Authorization\nRequires Y2Settings.Read scope", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Civilities returned" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving civilities" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/cegid/settings/countries": { "get": { "tags": [ "Cegid" ], "summary": "List Cegid countries and regions", "description": "Retrieves supported countries and regions from Cegid Y2 system with ISO codes and localization.\nUsed for customer registration form building and address validation configuration.\n\n## Use Cases\n- Populate country dropdowns in registration forms\n- Validate addresses against supported locations\n- Configure locale-specific field requirements\n- Support multi-country deployments\n\n## Authorization\nRequires Y2Settings.Read scope", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Countries and regions returned" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving countries" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/cegid/settings/countries/test": { "get": { "tags": [ "Cegid" ], "summary": "Verify country ISO code uniqueness", "description": "Validates that all country ISO codes in Cegid Y2 are unique with no conflicts.\nUsed for configuration diagnostics and integration health checks.\n\n## Validation Rules\n- ISO 3166-1 numeric codes (e.g., 250 for France) must be unique\n- ISO 3166-1 alpha-2 codes (e.g., FR) must be unique\n- ISO 3166-1 alpha-3 codes (e.g., FRA) must be unique\n- Duplicate values may indicate data corruption or configuration issues\n\n## Use Cases\n- Health check during integration setup\n- Diagnose duplicate country entries\n- Validate data integrity before production rollout\n\n## Authorization\nRequires Y2Settings.Read scope", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Duplicate ISO report returned" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while testing countries" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/cegid/settings/languages": { "get": { "tags": [ "Cegid" ], "summary": "List Cegid supported languages", "description": "Retrieves available language options from Cegid Y2 system for customer communication and interface localization.\nLanguages define how customer data and system text appear.\n\n## Language Configuration\nEach language includes:\n- Language ID and code (e.g., \"FR\", \"EN\", \"DE\")\n- Localized name (e.g., \"Français\", \"English\", \"Deutsch\")\n- Character encoding and collation settings\n- Regional locale configuration\n\n## Use Cases\n- Set customer preferred language for communication\n- Configure system UI language for country/region\n- Localize customer data entry and reporting\n- Support multi-language merchant deployments\n\n## Authorization\nRequires Y2Settings.Read scope", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Languages returned" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving languages" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/cegid/stores": { "get": { "tags": [ "Cegid" ], "summary": "List all Cegid Y2 stores", "description": "Retrieves the complete store catalog from Cegid Y2 system.\nPrimarily used as a configuration helper for administrative setup and integration diagnostics.\n\n## Use Cases\n- Configure store identifiers for transaction webhooks\n- Validate store existence before setting up locations\n- Display store list in admin configuration UI\n- Map incoming webhooks to correct tenant stores\n\n## Authorization\nRequires Y2Store.Read scope", "operationId": "Cegid-Store", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stores returned" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving stores" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/external/livestore": { "get": { "tags": [ "Cegid" ], "summary": "Redirect to LiveStore form with session context", "description": "Redirects customer to Cegid LiveStore form with pre-populated session and context data.\nUsed for seamless transitions between web experiences and in-store kiosks.\n\n## Redirect Parameters\nQuery parameters are passed as form pre-fill data to enable:\n- Customer context preservation\n- Session correlation\n- Pre-populated form fields\n\n## Use Cases\n- Mobile → Kiosk handoff (customer scans QR and gets LiveStore form with context)\n- Session recovery and continuity\n- Store-specific form customization\n\n## Authorization\nTenant context required via route parameter", "operationId": "Cegid-Livestore", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "style": "deepObject", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } ], "responses": { "302": { "description": "Redirect to LiveStore form with session context." }, "400": { "description": "Bad request for invalid parameters.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "204": { "description": "No content when session ID is missing." }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/external/livestore/session": { "get": { "tags": [ "Cegid" ], "summary": "Health check endpoint for LiveStore connectivity", "description": "Lightweight health check called by LiveStore to verify system availability.\nSupports both GET and HEAD requests for bandwidth optimization.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Service reachable." }, "500": { "description": "Unexpected server error." } } }, "head": { "tags": [ "Cegid" ], "summary": "Health check endpoint for LiveStore connectivity", "description": "Lightweight health check called by LiveStore to verify system availability.\nSupports both GET and HEAD requests for bandwidth optimization.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Service reachable." }, "500": { "description": "Unexpected server error." } } }, "post": { "tags": [ "Cegid" ], "summary": "Establish LiveStore session with customer context", "description": "Called by Cegid LiveStore to create a user session with customer information and context.\nEnables seamless handoff from in-store kiosk to mobile or web experiences.\n\n## Session Purpose\n- Preserves customer context across devices\n- Links kiosk interactions to customer profiles\n- Enables offer personalization by store and location\n- Supports omnichannel retail scenarios\n\n## Customer Payload\nContains customer identification and context:\n- Customer ID and identifiers\n- Store context and location\n- Session metadata and flags\n- Custom attributes from CRM\n\n## Authorization\nRequires `LiveStore.Access` scope with store provider validation.\n\n## Session Lifecycle\n1. LiveStore creates session and sends customer payload\n2. System stores session with TTL (time-to-live)\n3. Customer can use sessionId to access personalized experiences\n4. Session expires after configured timeout\n\n## Use Cases\n- Kiosk → Mobile transition (customer scans QR to complete on phone)\n- Store-specific offers and messaging\n- Loyalty integration at point-of-sale", "parameters": [ { "name": "sessionId", "in": "query", "description": "Session identifier.", "schema": { "type": "string" } }, { "name": "storeId", "in": "query", "description": "Optional store identifier.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Customer payload from LiveStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CustomerPayload" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CustomerPayload" } } } }, "responses": { "200": { "description": "Session stored." }, "401": { "description": "Unauthorized LiveStore access.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/external/secutix/orders/getTicketsUrl/{fileId}": { "get": { "tags": [ "Secutix" ], "summary": "Retrieve ticket URLs from Secutix file ID", "description": "Fetches ticket download URLs and metadata from Secutix system using a file identifier.\nUsed for order fulfillment, ticket distribution, and mobile pass generation.\n\n## Use Cases\n- Generate direct ticket download links for customers\n- Create mobile wallet passes with ticket data\n- Debug order fulfillment issues\n- Support ticket resale and transfers\n\n## Authorization\nRequires valid Secutix API credentials in tenant configuration", "parameters": [ { "name": "fileId", "in": "path", "description": "Secutix file identifier from order system", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ticket URL resolved." }, "401": { "description": "Unauthorized order access.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Order not found for the provided file identifier.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}": { "get": { "tags": [ "ApplePass" ], "summary": "Return serial numbers updated since the provided tag for a given device and pass type.", "description": "Called by Apple Wallet to poll for pass updates. Implements the PassKit protocol endpoint for retrieving modified pass serial numbers since a given timestamp.\n\n## Update Tag (Modification Timestamp)\nThe tag parameter represents the last modification timestamp the client knows about:\n- When provided: Returns only passes modified after this tag\n- When omitted: Returns all registered passes for the device/type combination\n- When no updates exist: Returns 204 No Content\n\n## Timestamp Format Evolution\n- **Legacy format (before 2024-10-07)**: Seconds since Unix epoch\n- **Current format**: Milliseconds since Unix epoch\nThe endpoint automatically detects and handles both formats for backward compatibility.\n\n## Polling Strategy\nApple Wallet uses this endpoint for efficient incremental sync of pass updates without downloading entire pass files.", "parameters": [ { "name": "deviceIdentifier", "in": "path", "description": "Device identifier used by Apple for authentication.", "required": true, "schema": { "type": "string" } }, { "name": "passTypeIdentifier", "in": "path", "description": "Apple pass type identifier.", "required": true, "schema": { "type": "string" } }, { "name": "passesUpdatedSince", "in": "query", "description": "Optional modification tag (timestamp). When omitted, all registrations are returned.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of updated pass serial numbers" }, "204": { "description": "No passes updated since the provided tag" }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while retrieving updated passes" } } } }, "/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}": { "delete": { "tags": [ "ApplePass" ], "summary": "Unregister pass removed from Apple device", "description": "Called by Apple Wallet when a pass is removed from a device. Stops push notifications to that device and cleans up device registration.\n\n## Unregistration Scenarios\nThis endpoint is triggered when:\n- User manually deletes the pass from Apple Wallet\n- Device is factory reset\n- App is uninstalled and reinstalled\n- Cloud backup/restore occurs\n\n## Device Registration Cleanup\n- Removes the device-pass mapping from the registration database\n- No further push notifications sent to this device for this pass\n- Pass can be re-added and re-registered by the user\n- Push token is safely discarded\n\n## Re-registration\nThe same device can re-add the pass later, which creates a new registration via the RegisterDevice endpoint with a fresh push token.\n\n## Authentication\nApple sends the same authorization token used during registration for verification.", "parameters": [ { "name": "deviceIdentifier", "in": "path", "description": "Unique identifier of the device.", "required": true, "schema": { "type": "string" } }, { "name": "passTypeIdentifier", "in": "path", "description": "Apple pass type identifier.", "required": true, "schema": { "type": "string" } }, { "name": "serialNumber", "in": "path", "description": "Serial number of the pass.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pass device registration removed" }, "401": { "description": "Authentication token invalid", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while removing device registration" } } }, "post": { "tags": [ "ApplePass" ], "summary": "Register pass installation on Apple device", "description": "Called by Apple Wallet when a pass is added to a device. Implements the PassKit Web Service device registration endpoint as specified by Apple's PassKit protocol.\n\n## Device Registration Flow\nWhen a user adds a pass to their Apple Wallet:\n1. Apple Wallet generates a unique device identifier\n2. The app extracts and sends the push token to this endpoint\n3. The push token enables server-to-device push notifications when pass data changes\n\n## Push Token Management\nThe push token is device and pass-specific. It changes when:\n- The device registers the same pass again\n- The app reinstalls\n- Apple infrastructure updates the token\n\n## Authentication\nApple sends an Authorization header with the pass's authentication token as:\n```\nAuthorization: ApplePass \n```\nThis token must match the pass's expected authentication value.\n\n## Idempotency\nCalling this endpoint multiple times with the same device and pass returns 200 OK for existing registrations, updating the push token. First registration returns 201 Created.", "parameters": [ { "name": "deviceIdentifier", "in": "path", "description": "Unique identifier of the device.", "required": true, "schema": { "type": "string" } }, { "name": "passTypeIdentifier", "in": "path", "description": "Apple pass type identifier.", "required": true, "schema": { "type": "string" } }, { "name": "serialNumber", "in": "path", "description": "Serial number of the pass.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Body containing `pushToken` to enable push updates.", "content": { "application/json": { "schema": { } }, "text/json": { "schema": { } }, "application/*+json": { "schema": { } } } }, "responses": { "200": { "description": "Device already registered or updated" }, "201": { "description": "Device newly registered" }, "401": { "description": "Authentication token invalid", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Pass serial number not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while processing device registration" } } } }, "/api/{tenantId}/passes/apple/{version}/log": { "post": { "tags": [ "ApplePass" ], "summary": "Log messages sent by Apple PassKit.", "description": "Endpoint to receive and log diagnostic information sent by Apple's PassKit service. Apple Wallet and PassKit framework send error and diagnostic messages to help debug pass delivery, installation, and update issues.\n\n## Diagnostic Information\nMessages may contain:\n- Pass installation failures\n- Push notification delivery errors\n- Device registration issues\n- Signature validation errors\n- Update retrieval failures\n\n## Log Format\nRequest body contains a JSON object:\n```json\n{\n \"logs\": [\n \"error message 1\",\n \"error message 2\"\n ]\n}\n```\n\n## Server-side Handling\nReceived logs are:\n- Stored in application logs with ERROR level\n- Associated with the device/pass that sent them\n- Useful for debugging why passes fail to update or install\n- Used for monitoring pass delivery health\n\n## Use Cases\n- Debug pass installation failures\n- Monitor PassKit framework issues\n- Identify signature validation problems\n- Troubleshoot push notification delivery", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "JSON object containing an array of log messages from Apple PassKit.", "content": { "application/json": { "schema": { } }, "text/json": { "schema": { } }, "application/*+json": { "schema": { } } } }, "responses": { "200": { "description": "Logs received and processed" }, "500": { "description": "Internal server error while processing logs" } } } }, "/api/{tenantId}/passes/apple/{version}/passes/{passTypeIdentifier}/{serialNumber}": { "get": { "tags": [ "ApplePass" ], "summary": "Retrieve the latest version of a pass for Apple Wallet.", "description": "Returns the current pass file in pkpass format. This endpoint supports conditional requests using standard HTTP caching headers to minimize bandwidth usage.\n\n## Conditional Requests (HTTP Caching)\nThe endpoint supports If-Modified-Since header for bandwidth optimization. When the pass has not been modified since the provided timestamp, the server returns 304 Not Modified to avoid transferring the pass file.", "parameters": [ { "name": "passTypeIdentifier", "in": "path", "description": "Apple pass type identifier.", "required": true, "schema": { "type": "string" } }, { "name": "serialNumber", "in": "path", "description": "Pass serial number.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pass file (pkpass) returned", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } }, "text/json": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "Pass unchanged since If-Modified-Since header" }, "400": { "description": "Invalid serial number", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "404": { "description": "Pass not found", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal server error while generating pass file" } } } }, "/api/{tenantId}/passes/google": { "post": { "tags": [ "GooglePass" ], "summary": "Handle Google Wallet pass state changes", "description": "Webhook endpoint called by Google when a pass is saved to or deleted from a device.\n\n## Supported Event Types\n- **save**: Pass added to Google Wallet on a user's device\n- **del**: Pass removed from Google Wallet on a user's device\n\n## Security & Verification\nGoogle signs all webhook messages using JWT. The system verifies the signature before processing any events.\nEnsures only authentic messages from Google are acted upon.\n\n## Deduplication\nUses the nonce field to prevent duplicate processing of the same event.\nAlready-processed messages are ignored and return 204 No Content.\n\n## Registration Tracking\n- Increments/decrements installation count for the pass\n- Tracks first installation date when count reaches 1\n- Updates aggregate active and total registration statistics", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Signed message envelope sent by Google.", "content": { "application/json": { "schema": { } }, "text/json": { "schema": { } }, "application/*+json": { "schema": { } } } }, "responses": { "200": { "description": "Pass state change processed successfully" }, "202": { "description": "Legacy pass format detected (cannot update)" }, "204": { "description": "Duplicate event or invalid message ignored" }, "404": { "description": "Pass not found by serial number", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Processing error during webhook handling" } } } }, "/api/{tenantId}/passes/google/signup": { "get": { "tags": [ "GooglePass" ], "summary": "Handle DiscoverableProgramMerchantSignupInfo flow redirect", "description": "Webhook endpoint used in Google Wallet's DiscoverableProgramMerchantSignupInfo flow.\nWhen users tap \"Sign up for more\" in Google Wallet, they are redirected to this endpoint.\n\n## User Profile Data\nGoogle provides optional user information in Base64-encoded JSON format:\n- First and last name\n- Address (street, city, zipcode, country)\n- Email address\n- Phone number\n\n## Parameter Mapping\nGoogle's field names (FIRST_NAME, LAST_NAME, etc.) are automatically mapped to\ncamelCase tenant-relative parameters (firstName, lastName, etc.) for the signup page.\n\n## Redirect Behavior\nCombines the provided relative URL with the public tenant URI and redirects the user\nto the signup page with mapped parameters as query string.", "parameters": [ { "name": "url", "in": "query", "description": "Tenant-relative layout path to redirect to.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "userProfile": { "type": "string", "description": "Base64-encoded JSON user profile provided by Google." } } }, "encoding": { "userProfile": { "style": "form" } } } } }, "responses": { "302": { "description": "Redirect to signup page with user data parameters" }, "400": { "description": "Invalid Base64 user profile or malformed JSON", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Error during URL construction or decoding" } } }, "post": { "tags": [ "GooglePass" ], "summary": "Handle DiscoverableProgramMerchantSignupInfo flow redirect", "description": "Webhook endpoint used in Google Wallet's DiscoverableProgramMerchantSignupInfo flow.\nWhen users tap \"Sign up for more\" in Google Wallet, they are redirected to this endpoint.\n\n## User Profile Data\nGoogle provides optional user information in Base64-encoded JSON format:\n- First and last name\n- Address (street, city, zipcode, country)\n- Email address\n- Phone number\n\n## Parameter Mapping\nGoogle's field names (FIRST_NAME, LAST_NAME, etc.) are automatically mapped to\ncamelCase tenant-relative parameters (firstName, lastName, etc.) for the signup page.\n\n## Redirect Behavior\nCombines the provided relative URL with the public tenant URI and redirects the user\nto the signup page with mapped parameters as query string.", "parameters": [ { "name": "url", "in": "query", "description": "Tenant-relative layout path to redirect to.", "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "userProfile": { "type": "string", "description": "Base64-encoded JSON user profile provided by Google." } } }, "encoding": { "userProfile": { "style": "form" } } } } }, "responses": { "302": { "description": "Redirect to signup page with user data parameters" }, "400": { "description": "Invalid Base64 user profile or malformed JSON", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Error during URL construction or decoding" } } } }, "/api/{tenantId}/webhooks/listeners/actito/custom-actions/updatePass": { "post": { "tags": [ "Actito" ], "summary": "Update passes via Actito marketing automation", "description": "Receives pass update events from Actito marketing automation platform.\nEnables dynamic pass content updates triggered by marketing campaigns and customer actions.\n\n## Update Triggers\nCan be triggered from Actito Journey Builder for:\n- Promotional offer updates\n- Loyalty point additions\n- Status changes\n- Personalized content delivery\n\n## Processing\nUpdates Apple Wallet and Google Wallet passes with new content.\nSends push notifications to customers for significant changes.\n\n## Authorization\nRequires ActitoListener.Write scope", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Actito pass update event payload", "content": { "application/json": { "schema": { } }, "text/json": { "schema": { } }, "application/*+json": { "schema": { } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/listeners/actito/profile/{eventType}": { "post": { "tags": [ "Actito" ], "summary": "Handle Actito profile creation and updates", "description": "Webhook endpoint called by Actito when customer profiles are created or updated.\n\n## Event Types\n- **CREATE**: New customer profile created in Actito\n- **UPDATE**: Existing customer profile modified\n\n## Integration Flow\n1. Actito sends webhook with profile event\n2. System retrieves full profile data from Actito API\n3. Updates local customer records\n4. Triggers pass updates if profile changes affect pass content\n\n## Use Cases\n- Customer data synchronization\n- Loyalty tier changes reflected in passes\n- Profile enrichment from marketing campaigns", "parameters": [ { "name": "eventType", "in": "path", "description": "CREATE or UPDATE.", "required": true, "schema": { "$ref": "#/components/schemas/ProfileEventType" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Actito event with profile identifier.", "content": { "application/json": { "schema": { "description": "Envelope for Actito webhook payloads.", "$ref": "#/components/schemas/NewProfileActitoWrapper" } }, "text/json": { "schema": { "description": "Envelope for Actito webhook payloads.", "$ref": "#/components/schemas/NewProfileActitoWrapper" } }, "application/*+json": { "schema": { "description": "Envelope for Actito webhook payloads.", "$ref": "#/components/schemas/NewProfileActitoWrapper" } } } }, "responses": { "200": { "description": "OK" }, "208": { "description": "Already Reported" }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/listeners/cegid/{connectionId}": { "get": { "tags": [ "Cegid" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/SubscriptionInformation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionInformation" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SubscriptionInformation" } } } } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] }, "post": { "tags": [ "Cegid" ], "summary": "Process Cegid Y2 business notifications", "description": "Receives real-time business event notifications from Cegid Y2 retail system.\n\n## Supported Event Types\n- **Customer Events**: Create, update, loyalty changes\n- **Sales Events**: Receipt creation, transaction completion\n- **Product Events**: Catalog changes (if configured)\n\n## Connection-Based Routing\nMultiple Cegid Y2 connections can be configured per tenant. The connectionId parameter routes events to the correct configuration.\n\n## Event Processing\n1. Validates connection exists in tenant configuration\n2. Parses event type from notification header\n3. Retrieves full entity data from Y2 if needed\n4. Triggers corresponding business logic (pass updates, customer sync, etc.)\n5. Emits internal events for further processing\n\n## Authorization\nRequires `Y2Listener.Write` scope - typically configured with Cegid Y2 webhook signature validation.\n\n## Example Events\n- CustomerCreated: New loyalty member enrolled\n- CustomerUpdated: Profile or tier change\n- ReceiptCreated: Purchase transaction completed", "parameters": [ { "name": "connectionId", "in": "path", "description": "Identifier of the configured Y2 connection", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Business notification event payload from Cegid Y2", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericEventData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GenericEventData" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GenericEventData" } } } }, "responses": { "200": { "description": "OK" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/listeners/cegid/{connectionId}/Register": { "post": { "tags": [ "Cegid" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/listeners/klaviyo/passes/pushUpdate": { "post": { "tags": [ "Klaviyo" ], "summary": "Update passes from Klaviyo campaigns", "description": "Called by Klaviyo flows to update wallet pass data based on customer segments and marketing automation.\n\n## Authorization\nRequires `KlaviyoListener.Write` scope.\n\n## Klaviyo Integration\nConfigured as a webhook action in Klaviyo flows:\n1. Klaviyo flow triggers (e.g., \"Customer entered VIP segment\")\n2. Flow sends webhook to this endpoint\n3. Pass is identified by custom identifiers (email, phone, customer ID)\n4. Pass data and metadata are updated\n5. Push notification sent to devices if installed\n\n## Identifiers\nFlexible identifier matching supports:\n- `email`: Customer email address\n- `phone`: Phone number\n- `customerId`: Internal customer ID\n- Any custom identifier configured in pass\n\n## Update Options\n- **passType**: Convert pass to different type (e.g., basic → premium)\n- **additionalData**: Update custom fields (points, tier, offers)\n- **updateMetadata**: Recompute pass visuals (slower, use only when needed)\n\n## Use Cases\n- Update loyalty points from campaign\n- Add birthday offer to pass\n- Upgrade tier based on purchase behavior\n- Add personalized coupon codes", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Pass identifiers and update payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushUpdateData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PushUpdateData" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PushUpdateData" } } } }, "responses": { "200": { "description": "Pass update accepted." }, "400": { "description": "Invalid or missing identifiers.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "401": { "description": "Unauthorized access to Klaviyo listener.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/listeners/klaviyo/profiles/sync": { "post": { "tags": [ "Klaviyo" ], "summary": "Synchronize Klaviyo customer profile", "description": "Receives and processes Klaviyo profile update webhooks for email and phone changes.\nQueues asynchronous tasks to synchronize data back to merchant systems.\n\n## Profile Updates Handled\n- Email address changes and subscriptions\n- Phone number updates\n- Consent and preference changes\n- Custom property modifications\n\n## Processing Flow\n1. Receive webhook with profile email and/or phone\n2. Find corresponding customer in local system\n3. Queue background task for synchronization\n4. Task updates customer record and associated passes\n5. Return 202 Accepted with correlation ID\n\n## Authorization\nRequires TenantConfigurationAccessControlled and ApiThrottling attributes", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Profile object with email and/or phone number for identification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } }, "text/json": { "schema": { "$ref": "#/components/schemas/Profile" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "responses": { "200": { "description": "Profile synchronization task scheduled." }, "401": { "description": "Unauthorized access to Klaviyo listener.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ "ScopedAuthorizeRequirement" ] }, { "apiKey": [ "ScopedAuthorizeRequirement" ] } ] } }, "/api/{tenantId}/webhooks/listeners/secutix/orders": { "post": { "tags": [ "Secutix" ], "summary": "Handle Secutix order state changes", "description": "Webhook endpoint called by Secutix when ticket orders change state (purchased, validated, refunded, etc.).\n\n## Order States\n- **PAID**: Order completed, tickets ready\n- **CANCELLED**: Order cancelled, refund processed\n- **VALIDATED**: Ticket scanned/used at venue\n- **MODIFIED**: Order details changed\n\n## Processing Flow\n1. Secutix sends webhook immediately when order state changes\n2. Endpoint validates request and schedules background task\n3. Background task retrieves full order details from Secutix API\n4. System creates/updates passes for tickets\n5. Push notifications sent to customer devices\n\n## Background Processing\nTasks are queued with correlation IDs for:\n- Retry handling on failures\n- Deduplication of rapid-fire updates\n- Performance monitoring\n\n## Use Cases\n- Generate event tickets as wallet passes\n- Update pass when ticket validated at gate\n- Cancel passes for refunded orders\n- Multi-ticket orders (family packages)", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Order change request with token, state, and ticket/movement IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderChangeRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OrderChangeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OrderChangeRequest" } } } }, "responses": { "200": { "description": "Order change queued for processing." }, "400": { "description": "Missing or invalid order token.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/sfmc/actions/notify/execute": { "post": { "tags": [ "SFMC" ], "summary": "Executes the Journey Builder notify action.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notifications dispatched." }, "404": { "description": "No matching passes found for provided identifiers.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/sfmc/actions/notify/publish": { "post": { "tags": [ "SFMC" ], "summary": "Handles publish handshakes from Journey Builder.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Publish handshake acknowledged." }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/sfmc/actions/pushupdate/execute": { "post": { "tags": [ "SFMC" ], "summary": "Executes the Journey Builder push update action.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pass updates scheduled." }, "404": { "description": "No matching passes found for provided identifiers.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/sfmc/actions/pushupdate/publish": { "post": { "tags": [ "SFMC" ], "summary": "Handles publish handshakes from Journey Builder.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Publish handshake acknowledged." }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/yurplan/{eventId}/order/confirmed": { "post": { "tags": [ "Yurplan" ], "summary": "Process Yurplan order confirmation", "description": "Webhook called when an event ticket order is confirmed and payment processed in Yurplan.\nCreates wallet passes for each ticket in the order.\n\n## Order Processing\n1. Yurplan confirms payment and finalizes order\n2. Webhook sends customer identifier and ticket list\n3. System emits order validated event (for CRM sync if needed)\n4. Creates wallet pass for each ticket with unique token\n\n## Pass Identification\nTickets are identified by: `yurplan.ticketId = {eventId}|{ticketToken}`\nThis composite key ensures uniqueness across events and platforms.\n\n## Use Cases\n- Generate event tickets as digital wallet passes\n- Automatic mobile ticket delivery\n- QR code for gate entry\n- Event updates and reminders via pass", "parameters": [ { "name": "eventId", "in": "path", "description": "Yurplan event identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Order details with ticket tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmedDataWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmedDataWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OrderConfirmedDataWebhookRequest" } } } }, "responses": { "200": { "description": "Order processed and passes created." }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/yurplan/{eventId}/ticket/canceled": { "post": { "tags": [ "Yurplan" ], "summary": "Handle Yurplan ticket cancellation", "description": "Called when a ticket is cancelled (refund or customer request).\nUpdates pass status and removes from customer wallet if needed.\n\n## Cancellation Handling\n- Marks pass as cancelled/expired\n- Triggers push notification for app users\n- Updates customer transaction history\n- May trigger refund workflows", "parameters": [ { "name": "eventId", "in": "path", "description": "Yurplan event identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Canceled ticket details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCanceledDataWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TicketCanceledDataWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TicketCanceledDataWebhookRequest" } } } }, "responses": { "200": { "description": "Cancellation processed." }, "500": { "description": "Unexpected server error." } } } }, "/api/{tenantId}/webhooks/listeners/yurplan/{eventId}/ticket/checked": { "post": { "tags": [ "Yurplan" ], "summary": "Handle Yurplan ticket check-in", "description": "Called when ticket is scanned/checked in at event entry point.\nUpdates pass status to indicate event attendance.\n\n## Check-in Processing\n- Marks pass as used/redeemed\n- Updates audit trail with entry timestamp\n- Triggers post-event marketing workflows\n- May enable post-event upsell or feedback requests\n\n## Analytics\nCheck-in data contributes to:\n- Event attendance metrics\n- Customer journey tracking\n- Pass engagement measurement", "parameters": [ { "name": "eventId", "in": "path", "description": "Yurplan event identifier.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Checked ticket details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCheckedDataWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TicketCheckedDataWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TicketCheckedDataWebhookRequest" } } } }, "responses": { "200": { "description": "Check-in processed." }, "500": { "description": "Unexpected server error." } } } }, "/api/admin/logs/connect": { "get": { "tags": [ "Logs" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ConnectResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConnectResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ConnectResult" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "admin-bearer": [ null ] } ] } }, "/api/admin/logs/ping": { "post": { "tags": [ "Logs" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } } } }, "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } } }, "security": [ { "admin-bearer": [ null ] } ] } }, "/api/info": { "get": { "tags": [ "Global" ], "summary": "Get system diagnostics and health information", "description": "Provides comprehensive runtime diagnostics for administrators to monitor application health and performance.\n\n## Authorization\n- Requires Global Administrator role", "responses": { "200": { "description": "Diagnostics collected successfully." }, "401": { "description": "Caller not authenticated with admin bearer token.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "403": { "description": "Caller is not a Global Administrator.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } }, "security": [ { "admin-bearer": [ null ] } ] } }, "/api/ping": { "get": { "tags": [ "Global" ], "summary": "Lightweight liveness/readiness probe.", "description": "Returns process and host lifetime state to confirm the app has fully started and is not stopping.", "responses": { "200": { "description": "Application is responding." }, "503": { "description": "Application is not ready yet." } } } }, "/api/swagger/tenantconfiguration/schema": { "get": { "tags": [ "TenantConfiguration" ], "summary": "Generate the OpenAPI schema and markdown documentation for tenant configuration.", "responses": { "200": { "description": "OK" } } } }, "/public/{tenantId}/{cacheKey}/{path}": { "get": { "tags": [ "Public" ], "summary": "Retrieve a public file from tenant storage", "description": "Serves files with automatic MIME detection and 100-day caching (client/CDN). `cacheKey` is used to force cache refresh when asset versions change.", "parameters": [ { "name": "path", "in": "path", "description": "The relative path of the file to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cacheKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File found and returned." }, "404": { "description": "File not found in tenant public directory.", "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } }, "text/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "$ref": "#/components/schemas/HttpValidationProblemDetails" } ] } } } }, "500": { "description": "Unexpected server error." } } } } }, "components": { "schemas": { "AddScanRequest": { "required": [ "data", "type" ], "type": "object", "properties": { "data": { "maxLength": 2048, "minLength": 3, "type": "string", "description": "Raw Data of the scan value" }, "type": { "description": "Type of data", "$ref": "#/components/schemas/TypeEnum" } }, "additionalProperties": false }, "AddScanResponse": { "required": [ "passId" ], "type": "object", "properties": { "passId": { "type": "string", "description": "Identifier of the pass" } }, "additionalProperties": false }, "Advisor": { "required": [ "advisorId", "displayName" ], "type": "object", "properties": { "advisorId": { "type": "string" }, "displayName": { "type": "string" } }, "additionalProperties": false }, "AparteConfigurationResponse": { "required": [ "baseUrl", "defaultPassType", "hasApiKey", "tenant" ], "type": "object", "properties": { "baseUrl": { "type": "string", "description": "Root URL of the Aparte WalletCrew API.", "format": "uri" }, "tenant": { "minLength": 1, "type": "string", "description": "Tenant identifier sent as the `X-Tenant` header." }, "defaultPassType": { "minLength": 1, "type": "string", "description": "Default pass type assigned to passes created from Aparte tickets." }, "hasApiKey": { "type": "boolean", "description": "Whether an API key is currently stored in the secret repository." } }, "additionalProperties": false, "description": "Response body for Aparte configuration." }, "ApiKeyCreatedResponse": { "required": [ "token" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiKeyDefinition" } ], "properties": { "token": { "type": "string", "description": "Plaintext API key. Copy and store it immediately — it will not be shown again." } }, "additionalProperties": false, "description": "Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again." }, "ApiKeyDefinition": { "required": [ "enabled", "name", "permissions" ], "type": "object", "properties": { "name": { "type": "string", "description": "Key name identifier." }, "enabled": { "type": "boolean", "description": "Whether this key is currently active." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "List of permission scopes granted to this key. Use `[\"*\"]` for full tenant-admin access." } }, "additionalProperties": false, "description": "API key definition returned by list and get endpoints.\nThe key hash is never exposed." }, "ApplyMovementRequest": { "required": [ "movementValue", "oldValue" ], "type": "object", "properties": { "oldValue": { "type": "number", "description": "The expected sum of all movement values before this update.\nUsed for optimistic concurrency control with server-side validation in the handler.\nIf the current value differs, the request is rejected (409 Conflict).", "format": "double" }, "movementValue": { "type": "number", "description": "The movement value to apply. Cannot be zero. Positive for issuance/award, negative for redemption/usage.\nFractional values are supported for progress-based privileges (e.g., 0.5 for half a stamp).", "format": "double" }, "remarks": { "maxLength": 500, "minLength": 1, "type": [ "null", "string" ], "description": "Optional remarks or debug information about this movement." } }, "additionalProperties": false, "description": "Request model to apply a movement (transaction) to a privilege's value." }, "BarcodeType": { "enum": [ "PDF417", "UPCA", "UPCE", "CODE39", "CODE93", "CODE128", "ITF14", "EAN13", "EAN8", "QRCODE" ], "type": "string" }, "ConnectResponse": { "type": "object", "properties": { "settings": { "oneOf": [ { "$ref": "#/components/schemas/CrewCheckSettings" } ], "description": "Settings related to the connected device" } }, "additionalProperties": false, "description": "Connect result information" }, "ConnectResult": { "type": "object", "properties": { "websocketUri": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" } }, "additionalProperties": false }, "ConnectionToken": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Device identifier." }, "tenantId": { "type": "string", "description": "Tenant identifier." }, "apiKey": { "type": "string", "description": "Issued API key for the device." }, "environment": { "type": "string", "description": "Environment base URI the device should call.", "format": "uri" } }, "additionalProperties": false, "description": "Connection token information returned to the device." }, "CreateApiKeyRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "Key name. Only alphanumeric characters, hyphens, underscores and dots are allowed." }, "enabled": { "type": "boolean", "description": "Whether this key is active. Defaults to `true`." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "List of permission scopes granted to this key. Use `[\"*\"]` for full access." } }, "additionalProperties": false, "description": "Request body to create an API key." }, "CreateDevice": { "type": "object", "properties": { "type": { "description": "Device type to create.", "$ref": "#/components/schemas/DeviceType" }, "name": { "type": "string", "description": "Device name." }, "description": { "type": [ "null", "string" ], "description": "Optional device description." } }, "additionalProperties": false, "description": "Payload to create a new device." }, "CreateOrUpdateModel": { "required": [ "layout" ], "type": "object", "properties": { "layout": { "minLength": 1, "type": "string", "description": "Name of the layout to create a redirection for" }, "parameters": { "type": "object", "additionalProperties": { "type": "string" }, "description": "List of parameters that should be included in the uri" }, "options": { "description": "Additional options for this redirect", "$ref": "#/components/schemas/WebRedirectOptions" } }, "additionalProperties": false }, "CreatePassData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PassData" } ], "properties": { "extensions": { "type": [ "null", "object" ], "additionalProperties": { "type": "null" }, "description": "Extensibility data related to this pass." } }, "additionalProperties": false, "description": "Data payload for pass creation operations." }, "CreateRoleRequest": { "required": [ "name", "permissions" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "Role name. Only alphanumeric characters, hyphens, underscores and dots are allowed.\nCannot be \"administrator\"." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "List of permission scopes granted to this role. Use [\"*\"] for full access." } }, "additionalProperties": false, "description": "Request body to create a role." }, "CreateTenantUserRequest": { "required": [ "email", "role" ], "type": "object", "properties": { "email": { "minLength": 1, "type": "string", "description": "User email address." }, "name": { "type": [ "null", "string" ], "description": "Display name." }, "role": { "minLength": 1, "type": "string", "description": "Tenant role to assign." } }, "additionalProperties": false, "description": "Request payload for creating a tenant user." }, "CrewCheckSettings": { "required": [ "logoUrl" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceSettingsBase" } ], "properties": { "logoUrl": { "type": "string", "description": "URL of the logo to display on the CrewCheck device." } }, "additionalProperties": false }, "CurrentTenantUser": { "required": [ "email", "permissions", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "User identifier." }, "email": { "minLength": 1, "type": "string", "description": "User email address." }, "displayName": { "type": [ "null", "string" ], "description": "User display name." }, "role": { "type": [ "null", "string" ], "description": "Tenant role assigned to the user.\nCan be globalAdministrator for global admins not assigned to a tenant role." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Expanded permissions for the current user." } }, "additionalProperties": false, "description": "Current authenticated tenant user representation." }, "CustomerPayload": { "required": [ "callbackUrl" ], "type": "object", "properties": { "callbackUrl": { "type": "string" }, "customerId": { "type": [ "null", "string" ] }, "storeId": { "type": [ "null", "string" ] } }, "additionalProperties": { } }, "Device": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Unique device identifier." }, "name": { "type": "string", "description": "Device name." }, "description": { "type": [ "null", "string" ], "description": "Optional description." }, "isEnabled": { "type": "boolean", "description": "Whether the device is currently active." }, "type": { "description": "Device type (CrewCheck, etc.).", "$ref": "#/components/schemas/DeviceType" }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/CrewCheckSettings" } ], "description": "Type-specific settings." } }, "additionalProperties": false, "description": "Device metadata exposed by the API." }, "DeviceSettingsBase": { "type": "object", "additionalProperties": false }, "DeviceType": { "enum": [ "CrewCheck" ], "type": "string" }, "EmailVerificationResult": { "type": "object", "properties": { "isValid": { "type": "boolean" } }, "additionalProperties": false }, "Execution": { "required": [ "duration", "id", "retryIndex", "startDate", "success" ], "type": "object", "properties": { "id": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "retryIndex": { "type": "integer", "format": "int32" }, "success": { "type": [ "null", "boolean" ] }, "duration": { "type": [ "null", "string" ], "format": "date-span" } }, "additionalProperties": false }, "ExecutionDetail": { "required": [ "logs" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/Execution" } ], "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionLog" } } }, "additionalProperties": false }, "ExecutionLog": { "required": [ "data", "entryType", "eventDate", "id" ], "type": "object", "properties": { "id": { "type": "string" }, "eventDate": { "type": "string", "format": "date-time" }, "entryType": { "type": "string" }, "data": { "type": [ "null", "string" ] } }, "additionalProperties": false }, "ExecutionSummary": { "required": [ "taskId", "taskType" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/Execution" } ], "properties": { "taskId": { "type": "string", "description": "Identifier of the scheduled task (as declared in scheduler.yml), extracted from the CorrelationId." }, "taskType": { "type": [ "null", "string" ], "description": "Task type (handler) reported by the scheduler telemetry." } }, "additionalProperties": false }, "FilterAction": { "enum": [ 0, 1 ], "type": "integer", "format": "int32" }, "FilterInformation": { "type": "object", "properties": { "eventSources": { "type": "array", "items": { "type": "string" } }, "userIds": { "type": "array", "items": { "type": "string" } }, "action": { "$ref": "#/components/schemas/FilterAction" } }, "additionalProperties": false }, "FilterModel": { "type": "object", "properties": { "field": { "type": "string", "description": "Field to filter by (identifiers.*, metadata.*, passType, installationStatus)." }, "operator": { "description": "Comparison operator to apply.", "$ref": "#/components/schemas/FilterModelOperator" }, "value": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Filter values. Single-element for most operators; multiple elements for `in` and `notIn`.\nThe query parameter name is `value` (repeated for multiple values).\n\nSingle value (equals, contains, startsWith, …):\n```\nGET /passes?filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding\n```\nMultiple values (in / notIn):\n```\nGET /passes?filter[0].field=passType&filter[0].operator=in&filter[0].value=boarding&filter[0].value=loyalty\n```\nMultiple filters combined:\n```\nGET /passes?filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding\n &filter[1].field=identifiers.customerId&filter[1].operator=startsWith&filter[1].value=CUST-\n```" } }, "additionalProperties": false, "description": "Filter specification for pass queries." }, "FilterModelOperator": { "enum": [ "Contains", "StartsWith", "EndsWith", "Equals", "IsEmpty", "IsNotEmpty", "NotEquals", "In", "NotIn" ], "type": "string", "description": "Filter operators for pass list queries." }, "GenericEventData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/JsonElementDataWrapper" } ], "additionalProperties": false }, "Header": { "type": "object", "properties": { "EventId": { "type": "string" }, "EventSource": { "type": "string" }, "ContentType": { "type": "string" }, "SourceId": { "type": "string" }, "UserId": { "type": "string" }, "Date": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." } }, "additionalProperties": false }, "HttpValidationProblemDetails": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" } ], "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": { } }, "InsertOptions": { "type": "object", "properties": { "correlationId": { "maxLength": 100, "minLength": 10, "type": [ "null", "string" ], "description": "Correlation identifier to group and trace related API calls." }, "notification": { "description": "Optional notification to send to the pass when the privilege is applied.\nMirrors the payload accepted by the notification endpoints.", "$ref": "#/components/schemas/NotifyRequest" } }, "additionalProperties": false, "description": "Configuration options for privilege creation, including correlation tracking and notifications." }, "InsertPrivilegeRequest": { "required": [ "type" ], "type": "object", "allOf": [ { "description": "Base request model for privilege operations.", "$ref": "#/components/schemas/PrivilegeRequestBase" } ], "properties": { "type": { "description": "The functional type of the privilege (required for new privileges).", "$ref": "#/components/schemas/PrivilegeType" }, "options": { "description": "Additional processing options for privilege creation.", "$ref": "#/components/schemas/InsertOptions" } }, "additionalProperties": false, "description": "Request model to create a new privilege." }, "JsonElementDataWrapper": { "type": "object", "properties": { "__id": { "type": "string" }, "__creationDate": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." }, "__eventName": { "type": "string" }, "Header": { "$ref": "#/components/schemas/Header" }, "Body": { } }, "additionalProperties": false }, "LocalizedString": { "type": "object", "properties": { "value": { "type": [ "null", "string" ], "description": "The default text in the primary language." }, "values": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Localized translations by language code.\nKey: ISO 639-1 code or \"iso2-region\" (e.g., \"en\", \"en-US\").\nValue: The translated string for that language.", "propertyNames": { "pattern": "^[a-z]{2}(-[A-Z]{2})?$" } } }, "additionalProperties": false, "description": "Represents a localized string with a default value and optional per-language translations." }, "MovementResponse": { "type": "object", "properties": { "movementId": { "type": "string" } }, "additionalProperties": false, "description": "Response payload after a movement is created." }, "MultipleUpdatePassData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/MultipleUpdatePassDataOptionsUpdatePassData" } ], "additionalProperties": false, "description": "Data payload for multi-pass (bulk) update operations." }, "MultipleUpdatePassDataOptions": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UpdatePassDataOptions" } ], "properties": { "throughput": { "type": "number", "description": "Desired throughput (passes per second) when scheduling updates. Default is 12. Throughput is best-effort and can vary. Values below 1 slowly pace updates.", "format": "float" } }, "additionalProperties": false, "description": "Options for multi-pass (bulk) update operations." }, "MultipleUpdatePassDataOptionsUpdatePassData": { "type": "object", "properties": { "identifiers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "External identifiers of the customer for this pass. Keys must not start with `id.`; common examples are `y2.customerId` or `shopify.customerId`.\nUse an empty value to remove an identifier. Leave the collection empty to keep existing identifiers unchanged." }, "additionalData": { "type": [ "null", "object" ], "additionalProperties": { "type": "null" }, "description": "Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags)." }, "passType": { "type": [ "null", "string" ], "description": "Optional pass type to convert the pass to." }, "updateMetadata": { "type": "boolean", "description": "Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update", "default": false, "deprecated": true }, "options": { "description": "Options for multi-pass (bulk) update operations.", "$ref": "#/components/schemas/MultipleUpdatePassDataOptions" } }, "additionalProperties": false }, "NewProfile": { "type": "object", "properties": { "profileId": { "type": "integer", "description": "Numeric profile identifier.", "format": "int64" } }, "additionalProperties": false, "description": "Minimal profile identifier payload from Actito." }, "NewProfileActitoWrapper": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Type of the event emitted by Actito." }, "operation": { "type": "string", "description": "Operation name provided by Actito." }, "data": { "description": "Event-specific payload.", "$ref": "#/components/schemas/NewProfile" } }, "additionalProperties": false, "description": "Envelope for Actito webhook payloads." }, "NotifyRequest": { "type": "object", "properties": { "content": { "type": [ "null", "string" ], "description": "Could be null if LocalizedContent is specified" }, "localizedContent": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Localized notification content by language code.\nKey: ISO 639-1 code or \"iso2-region\" (e.g., \"en\", \"en-US\").\nValue: The notification content for that language.", "propertyNames": { "pattern": "^[a-z]{2}(-[A-Z]{2})?$" } }, "options": { "$ref": "#/components/schemas/NotifyRequestOptions" } }, "additionalProperties": false }, "NotifyRequestOptions": { "type": "object", "properties": { "updateData": { "type": "boolean", "description": "Indicate if pass data should also be updated when the notification is sent.", "default": false }, "correlationId": { "maxLength": 100, "minLength": 10, "type": [ "null", "string" ], "description": "Correlation identifier to group and trace related API calls." } }, "additionalProperties": false }, "OptionsRequest": { "type": "object", "properties": { "expiresOn": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "After this UTC date/time the secret becomes inaccessible. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." }, "notBefore": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Before this UTC date/time the secret cannot be accessed. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." } }, "additionalProperties": false, "description": "Optional validity window for the secret." }, "OrderChangeRequest": { "required": [ "lastUpdate", "orderSecretToken", "state" ], "type": "object", "properties": { "ticketId": { "type": [ "null", "integer" ], "description": "Ticket identifier from Secutix, when available.", "format": "int64" }, "saleMovementId": { "type": [ "null", "integer" ], "description": "Sale movement identifier from Secutix, when available.", "format": "int64" }, "orderSecretToken": { "type": "string", "description": "Secret token identifying the order." }, "state": { "type": "string", "description": "Current state reported by Secutix (PAID, CANCELLED, VALIDATED, etc.)." }, "lastUpdate": { "type": "string", "description": "Last update timestamp provided by Secutix." } }, "additionalProperties": false }, "OrderConfirmedData": { "type": "object", "properties": { "identifier": { "type": "string" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/TicketData" } } }, "additionalProperties": false }, "OrderConfirmedDataWebhookRequest": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrderConfirmedData" } }, "additionalProperties": false }, "Pass": { "type": "object", "properties": { "id": { "type": "string", "description": "Platform-assigned unique pass identifier. This is a random alphanumeric string generated at creation time and cannot be set by callers (e.g., `xK9mP2nQr7sT`)." }, "secret": { "type": "string", "description": "Platform-generated opaque token used internally to authenticate pass delivery. Read-only; treat as confidential." }, "creationDate": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Timestamp when the pass was created by the platform. Read-only. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." }, "lastUpdateDate": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Timestamp of the most recent update. Equals `CreationDate` when no update has occurred. Read-only. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." }, "passType": { "type": "string", "description": "Type of pass, matching a file in the tenant `server/passes/` configuration." }, "identifiers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "External identifiers keyed by system name (e.g., `shopify.customerId`)." }, "metadata": { "type": "object", "additionalProperties": { "type": "null" }, "description": "Computed metadata fields managed by the platform." }, "additionalData": { "type": "object", "additionalProperties": { "type": "null" }, "description": "Arbitrary key/value data persisted with the pass." }, "providers": { "type": "object", "additionalProperties": { }, "description": "Installation details keyed by provider name (e.g., `apple`, `google`). Populated by the platform. Read-only." } }, "additionalProperties": false, "description": "Represents a pass returned by the API." }, "PassConnectResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "WebSocket URL to connect for pass notifications." } }, "additionalProperties": false, "description": "Represents a Web PubSub connection response for a pass." }, "PassData": { "type": "object", "properties": { "identifiers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "External identifiers of the customer for this pass. Keys must not start with `id.`; common examples are `y2.customerId` or `shopify.customerId`.\nUse an empty value to remove an identifier. Leave the collection empty to keep existing identifiers unchanged." }, "additionalData": { "type": [ "null", "object" ], "additionalProperties": { "type": "null" }, "description": "Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags)." } }, "additionalProperties": false }, "PassStatistic": { "type": "object", "properties": { "count": { "description": "Number of active pass", "$ref": "#/components/schemas/PassStatisticCount" } }, "additionalProperties": false, "description": "Get statistics about pass usage" }, "PassStatisticCount": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of passes", "format": "int32" }, "active": { "type": "integer", "description": "Total number of installed pass", "format": "int32" }, "apple": { "type": "integer", "description": "Total number of active pass for apple", "format": "int32" }, "google": { "type": "integer", "description": "Total number of active pass for google", "format": "int32" } }, "additionalProperties": false, "description": "Get number of active passes per device" }, "PatchOptions": { "type": "object", "properties": { "correlationId": { "maxLength": 100, "minLength": 10, "type": [ "null", "string" ], "description": "Correlation identifier to group and trace related API calls." }, "notification": { "description": "Optional notification to send to the pass when the privilege is updated.\nMirrors the payload accepted by the notification endpoints.", "$ref": "#/components/schemas/NotifyRequest" } }, "additionalProperties": false, "description": "Configuration options for privilege patching, including correlation tracking and notifications." }, "PatchPrivilegeRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PrivilegeRequestBase" } ], "properties": { "type": { "description": "The functional type of the privilege (optional for patches).", "$ref": "#/components/schemas/PrivilegeType" }, "options": { "description": "Additional processing options for privilege patching.", "$ref": "#/components/schemas/PatchOptions" } }, "additionalProperties": false, "description": "Request model to patch an existing privilege." }, "PermissionAreaWeb": { "required": [ "category", "code", "scopes" ], "type": "object", "properties": { "code": { "type": "string", "description": "Area code grouping related scopes." }, "category": { "type": "string", "description": "Top-level category code used to group permission areas in the UI." }, "description": { "type": [ "null", "string" ], "description": "Human-friendly description of the area." }, "scopes": { "type": "array", "items": { "description": "Web response for an available permission scope", "$ref": "#/components/schemas/PermissionScopeWeb" }, "description": "Scopes exposed by this permission area." } }, "additionalProperties": false, "description": "Web response for a permission area (category of scopes)" }, "PermissionScopeWeb": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "Scope code used for access checks." }, "description": { "type": [ "null", "string" ], "description": "Human-friendly description of the scope." } }, "additionalProperties": false, "description": "Web response for an available permission scope" }, "Privilege": { "required": [ "privilegeId" ], "type": "object", "allOf": [ { "description": "Base model for privilege definitions, including classification, visuals, links, and state.", "$ref": "#/components/schemas/PrivilegeBase" } ], "properties": { "privilegeId": { "type": "string", "description": "Unique identifier of the privilege (unique across all passes within the tenant)." } }, "additionalProperties": false, "description": "Represents a persisted privilege with a required unique identifier." }, "PrivilegeAppearance": { "type": "object", "properties": { "mainImageUrl": { "description": "URL of the main image representing the privilege.", "$ref": "#/components/schemas/LocalizedString" }, "thumbnailUrl": { "description": "URL of the thumbnail image for the privilege.", "$ref": "#/components/schemas/LocalizedString" }, "backgroundColor": { "type": [ "null", "string" ], "description": "Background color (e.g., HEX code)." }, "foregroundColor": { "type": [ "null", "string" ], "description": "Foreground color for text or icons (e.g., HEX code)." } }, "additionalProperties": false, "description": "Visual appearance settings for a privilege." }, "PrivilegeBase": { "required": [ "type" ], "type": "object", "properties": { "externalId": { "maxLength": 100, "minLength": 1, "type": [ "null", "string" ], "description": "External identifier for the privilege in the source system." }, "priority": { "type": [ "null", "integer" ], "description": "Priority of the privilege. Larger numbers indicate higher importance (e.g., 100 > 10).", "format": "int32" }, "origin": { "description": "Information about the external system that produced this privilege.", "$ref": "#/components/schemas/PrivilegeOrigin" }, "type": { "description": "The functional type of the privilege.", "$ref": "#/components/schemas/PrivilegeType" }, "categories": { "type": "array", "items": { "description": "High-level classification of privileges for organization and filtering.", "$ref": "#/components/schemas/PrivilegeCategory" }, "description": "Categories used to classify and filter the privilege." }, "content": { "description": "Localized content such as title, description, and activation notifications.", "$ref": "#/components/schemas/PrivilegeContent" }, "appearance": { "description": "Visual appearance settings (images and colors).", "$ref": "#/components/schemas/PrivilegeAppearance" }, "links": { "description": "Links relevant to the privilege (e.g., legal terms, call to action).", "$ref": "#/components/schemas/PrivilegeLinks" }, "data": { "description": "Current state and payload of the privilege (e.g., whether it is available or already used).", "$ref": "#/components/schemas/PrivilegeData" }, "deletionDate": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "The timestamp at which this privilege should be removed from the system. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." } }, "additionalProperties": false, "description": "Base model for privilege definitions, including classification, visuals, links, and state." }, "PrivilegeCategory": { "enum": [ "Other", "Gift", "Access", "AudioGuide" ], "type": "string", "description": "High-level classification of privileges for organization and filtering." }, "PrivilegeContent": { "type": "object", "properties": { "title": { "description": "The privilege title, localized for multiple languages.", "$ref": "#/components/schemas/LocalizedString" }, "description": { "description": "A detailed description of the privilege, localized for multiple languages.", "$ref": "#/components/schemas/LocalizedString" } }, "additionalProperties": false, "description": "Localized content for a privilege (title, description, notifications)." }, "PrivilegeData": { "type": "object", "properties": { "value": { "type": [ "null", "number" ], "description": "Current numeric value of the privilege (e.g., loyalty points, punch count).\nThis is computed as the sum of all movement values. Can be negative if partially redeemed or adjusted. \nCan be fractional for progress-based privileges.", "format": "double" }, "movements": { "type": "array", "items": { "description": "Represents a single movement or transaction affecting a privilege's value.", "$ref": "#/components/schemas/PrivilegeMovement" }, "description": "History of all movements (transactions) affecting this privilege's data.\nThe current value is computed as the sum of all movement values." }, "content": { "maxLength": 500, "minLength": 1, "type": [ "null", "string" ], "description": "Optional provider-specific payload or metadata for the privilege data." } }, "additionalProperties": false, "description": "Runtime state and payload associated with a privilege." }, "PrivilegeLink": { "required": [ "link" ], "type": "object", "properties": { "title": { "description": "Localized title to display for the link.", "$ref": "#/components/schemas/LocalizedString" }, "link": { "type": "string", "description": "Target URI of the link.", "format": "uri" } }, "additionalProperties": false, "description": "A single link with a localized title and a target URI." }, "PrivilegeLinks": { "type": "object", "properties": { "legalInformation": { "description": "Link to legal or terms-of-service information for the privilege.", "$ref": "#/components/schemas/PrivilegeLink" }, "callToAction": { "description": "Call-to-action link (e.g., redeem, learn more).", "$ref": "#/components/schemas/PrivilegeLink" } }, "additionalProperties": false, "description": "A set of related links associated with a privilege." }, "PrivilegeMovement": { "required": [ "date", "movementId", "value" ], "type": "object", "properties": { "movementId": { "type": "string", "description": "Unique identifier for this movement." }, "date": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Timestamp when this movement occurred. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." }, "value": { "type": "number", "description": "Change in value. Negative when the privilege is used/redeemed.\nFractional for progress-based privileges (e.g., 0.5 for half a stamp).", "format": "double" }, "remarks": { "maxLength": 500, "minLength": 1, "type": [ "null", "string" ], "description": "Optional remarks or debug information about this movement." } }, "additionalProperties": false, "description": "Represents a single movement or transaction affecting a privilege's value." }, "PrivilegeOrigin": { "type": "object", "properties": { "externalId": { "maxLength": 100, "minLength": 1, "type": [ "null", "string" ], "description": "External identifier of this privilege in the partner system." }, "generator": { "maxLength": 100, "minLength": 1, "type": [ "null", "string" ], "description": "Name of the partner or upstream system that generated the privilege." }, "processId": { "maxLength": 100, "minLength": 1, "type": [ "null", "string" ], "description": "Identifier of the upstream process or job that created this privilege." } }, "additionalProperties": false, "description": "Describes the origin of a privilege in an external/partner system." }, "PrivilegeRequestBase": { "type": "object", "properties": { "externalId": { "maxLength": 100, "minLength": 1, "type": [ "null", "string" ], "description": "External identifier for the privilege in the source system." }, "priority": { "type": [ "null", "integer" ], "description": "Priority of the privilege. Larger numbers indicate higher importance.", "format": "int32" }, "origin": { "description": "Information about the external system that produced this privilege.", "$ref": "#/components/schemas/PrivilegeOrigin" }, "categories": { "type": "array", "items": { "description": "High-level classification of privileges for organization and filtering.", "$ref": "#/components/schemas/PrivilegeCategory" }, "description": "Categories used to classify and filter the privilege." }, "content": { "description": "Localized content such as title and description.", "$ref": "#/components/schemas/PrivilegeContent" }, "appearance": { "description": "Visual appearance settings (images and colors).", "$ref": "#/components/schemas/PrivilegeAppearance" }, "links": { "description": "Links relevant to the privilege (e.g., legal terms, call to action).", "$ref": "#/components/schemas/PrivilegeLinks" }, "data": { "description": "Current state and payload of the privilege.", "$ref": "#/components/schemas/PrivilegeData" }, "deletionDate": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "The timestamp at which this privilege should be removed from the system. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." } }, "additionalProperties": false, "description": "Base request model for privilege operations." }, "PrivilegeType": { "enum": [ "OneTime", "Unlimited", "MultiUse", "Unlockable" ], "type": "string", "description": "Defines how a privilege behaves from a usage perspective." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "type": [ "null", "integer" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } }, "additionalProperties": { } }, "Profile": { "type": "object", "properties": { "email": { "type": [ "null", "string" ], "description": "Customer email address used for synchronization." }, "phone_number": { "type": [ "null", "string" ], "description": "Customer phone number used for synchronization." } }, "additionalProperties": false }, "ProfileEventType": { "enum": [ "Create", "Update" ], "type": "string" }, "PushUpdateData": { "required": [ "identifiers" ], "type": "object", "properties": { "identifiers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Identifiers used to locate the target pass (email, phone, customerId, etc.)." }, "passType": { "type": [ "null", "string" ], "description": "Optional pass type to convert the pass to." }, "additionalData": { "type": [ "null", "object" ], "additionalProperties": { "type": "null" }, "description": "Custom data applied to the pass payload." }, "updateMetadata": { "type": "boolean", "description": "When true, recomputes pass metadata and visuals.", "default": false } }, "additionalProperties": false }, "PushUpdateResult": { "type": "object", "properties": { "passCount": { "type": "integer", "description": "Count of passes scheduled for update.", "format": "int32" } }, "additionalProperties": false, "description": "Result returned after scheduling a bulk push update operation." }, "PushUpdateStatistics": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique operation identifier." }, "operationName": { "type": "string", "description": "Operation name/category." }, "operationData": { "type": "string", "description": "Correlation ID for tracking related updates." }, "startDate": { "type": "string", "description": "Operation start timestamp.", "format": "date-time" }, "lastActivity": { "type": [ "null", "string" ], "description": "Last activity timestamp.", "format": "date-time" }, "passCount": { "type": "integer", "description": "Total passes scheduled for update.", "format": "int32" }, "completed": { "type": "integer", "description": "Number of passes successfully updated.", "format": "int32" }, "errors": { "type": "integer", "description": "Number of passes with update errors.", "format": "int32" }, "apple": { "type": "integer", "description": "Number of Apple Pass updates deployed.", "format": "int32" }, "google": { "type": "integer", "description": "Number of Google Pass updates deployed.", "format": "int32" }, "isCanceled": { "type": "boolean", "description": "Whether the operation was cancelled." } }, "additionalProperties": false, "description": "Aggregated status of a push update operation." }, "QueryOptions": { "type": "object", "additionalProperties": false }, "QueryRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "$ref": "#/components/schemas/QueryOptions" } }, "additionalProperties": false }, "QueryResponse": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { } } } }, "additionalProperties": false }, "RenderTemplateRequest": { "required": [ "templates" ], "type": "object", "properties": { "culture": { "type": [ "null", "string" ], "description": "Optional BCP 47 culture tag (e.g. \"en\", \"fr-FR\"). Defaults to the server's current culture when omitted." }, "templates": { "type": "array", "items": { "type": "string" }, "description": "One or more Liquid template strings to render." }, "context": { "type": [ "null", "object" ], "additionalProperties": { }, "description": "Key/value pairs made available to every template during rendering." } }, "additionalProperties": false, "description": "Request body for rendering Liquid templates." }, "RenderTemplateResponse": { "required": [ "results" ], "type": "object", "properties": { "results": { "type": "array", "items": { "type": "string" }, "description": "Index-aligned rendered outputs. `Results[i]` corresponds to `Templates[i]`.\nThe value is `null` when the template at that index failed to render (see Neo.Web.Api.Template.Controllers.TemplatesController.RenderTemplateResponse.Errors)." }, "errors": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Index-aligned Liquid error messages. Only present when at least one template failed.\n`Errors[i]` is `null` when `Results[i]` rendered successfully." } }, "additionalProperties": false, "description": "Response body returned by M:Neo.Web.Api.Template.Controllers.TemplatesController.Render(Neo.Web.Api.Template.Controllers.TemplatesController.RenderTemplateRequest,System.Threading.CancellationToken)." }, "RoleDefinition": { "required": [ "name", "permissions" ], "type": "object", "properties": { "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "SchedulerSortModel": { "type": "object", "properties": { "field": { "type": "string", "description": "Field to sort by (startDate, taskId, taskType, duration, retryIndex)." }, "direction": { "description": "Sort direction (ASC or DESC).", "$ref": "#/components/schemas/SchedulerSortModelDirection" } }, "additionalProperties": false, "description": "Sort specification for scheduler execution queries." }, "SchedulerSortModelDirection": { "enum": [ 0, 1 ], "type": "integer", "description": "Sort direction for scheduler execution list queries.", "format": "int32" }, "SetAparteRequest": { "required": [ "baseUrl", "defaultPassType", "tenant" ], "type": "object", "properties": { "baseUrl": { "type": "string", "description": "Root URL of the Aparte WalletCrew API.", "format": "uri" }, "tenant": { "minLength": 1, "type": "string", "description": "Tenant identifier sent as the `X-Tenant` header." }, "defaultPassType": { "minLength": 1, "type": "string", "description": "Default pass type assigned to passes created from Aparte tickets." }, "apiKey": { "type": [ "null", "string" ], "description": "API key sent as the `X-Api-Key` header.\nStored in the secret repository under `APARTE-APIKEY`.\nWhen omitted, the existing secret is preserved." } }, "additionalProperties": false, "description": "Request body for setting Aparte configuration." }, "SetRequest": { "required": [ "value" ], "type": "object", "properties": { "value": { "type": "string", "description": "Secret value to store." }, "options": { "description": "Optional validity window for the secret.", "$ref": "#/components/schemas/OptionsRequest" } }, "additionalProperties": false }, "SetTurnstileRequest": { "required": [ "proofCookieValidityDurationSeconds", "siteKey" ], "type": "object", "properties": { "siteKey": { "minLength": 1, "type": "string", "description": "Public site key used by the web client to render the Turnstile widget." }, "secretKey": { "type": [ "null", "string" ], "description": "Secret key used by the server to verify Turnstile tokens.\nStored in the secret repository under `CLOUDFLARE-TURNSTILE-SECRETKEY`.\nWhen omitted, the existing secret is preserved." }, "proofCookieValidityDurationSeconds": { "type": "integer", "description": "Duration in seconds the proof cookie remains valid after a successful challenge.\nSet to 0 to disable the proof cookie bypass.", "format": "int32" } }, "additionalProperties": false, "description": "Request body for setting Turnstile configuration." }, "SingleUpdatePassData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SingleUpdatePassDataOptionsUpdatePassData" } ], "properties": { "bypassQueue": { "type": "boolean", "description": "Indicates whether the push update should bypass the queue and run immediately. Queuing helps protect the system load and should only be bypassed when required.", "default": false, "deprecated": true } }, "additionalProperties": false, "description": "Data payload for single pass update operations." }, "SingleUpdatePassDataOptions": { "type": "object", "allOf": [ { "description": "Options used when updating passes.", "$ref": "#/components/schemas/UpdatePassDataOptions" } ], "properties": { "bypassQueue": { "type": "boolean", "description": "Indicates whether the push update should bypass the queue and run immediately. Queuing helps protect the system load and should only be bypassed when required.", "default": false } }, "additionalProperties": false, "description": "Options for single pass update operations. Metadata recomputation is enabled by default.\nUse Neo.Web.Api.Controllers.PassController.SingleUpdatePassDataOptions.BypassQueue to apply the update synchronously instead of queueing." }, "SingleUpdatePassDataOptionsUpdatePassData": { "type": "object", "properties": { "identifiers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "External identifiers of the customer for this pass. Keys must not start with `id.`; common examples are `y2.customerId` or `shopify.customerId`.\nUse an empty value to remove an identifier. Leave the collection empty to keep existing identifiers unchanged." }, "additionalData": { "type": [ "null", "object" ], "additionalProperties": { "type": "null" }, "description": "Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags)." }, "passType": { "type": [ "null", "string" ], "description": "Optional pass type to convert the pass to." }, "updateMetadata": { "type": "boolean", "description": "Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update", "default": false, "deprecated": true }, "options": { "description": "Options for single pass update operations. Metadata recomputation is enabled by default.\nUse Neo.Web.Api.Controllers.PassController.SingleUpdatePassDataOptions.BypassQueue to apply the update synchronously instead of queueing.", "$ref": "#/components/schemas/SingleUpdatePassDataOptions" } }, "additionalProperties": false }, "SortModel": { "type": "object", "properties": { "field": { "type": "string", "description": "Field to sort by." }, "direction": { "description": "Sort direction (ASC or DESC).", "$ref": "#/components/schemas/SortModelDirection" } }, "additionalProperties": false, "description": "Sort specification for pass queries." }, "SortModelDirection": { "enum": [ 0, 1 ], "type": "integer", "description": "Sort direction for pass list queries.", "format": "int32" }, "Store": { "required": [ "displayName", "storeId" ], "type": "object", "properties": { "storeId": { "type": "string" }, "displayName": { "type": "string" }, "availableLanguages": { "type": [ "null", "array" ], "items": { "type": "string" } }, "additionalResources": { "type": [ "null", "object" ], "additionalProperties": { } }, "additionalProperties": { "type": [ "null", "object" ], "additionalProperties": { } } }, "additionalProperties": false }, "SubscriptionInformation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "user": { "$ref": "#/components/schemas/UserInformation" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FilterInformation" } } }, "additionalProperties": false }, "TOptions": { "type": "object", "properties": { "updateMetadata": { "type": "boolean", "description": "When true, recompute and persist pass metadata. Updating metadata is slower and is usually unnecessary for notification-only updates." }, "correlationId": { "type": [ "null", "string" ], "description": "Groups related updates under the same correlationId. Useful for batch updates (for example nightly jobs) to make retries and logs traceable." } }, "additionalProperties": false }, "TenantConfigFaviconsWeb": { "required": [ "rawFaviconUrl" ], "type": "object", "properties": { "faviconUrl": { "type": [ "null", "string" ], "description": "Resolved 192x192 favicon URL. Can be a full URL or fallback data URL." }, "rawFaviconUrl": { "minLength": 1, "type": "string", "description": "Raw 48x48 favicon URL from `config.yml`." }, "rawLargeFaviconUrl": { "type": [ "null", "string" ], "description": "Raw 192x192 favicon URL from `config.yml`." }, "rawAppleFaviconUrl": { "type": [ "null", "string" ], "description": "Raw Apple touch icon URL from `config.yml`." } }, "additionalProperties": false, "description": "Favicon URLs for tenant configuration response." }, "TenantConfigWeb": { "required": [ "availableLanguages", "defaultLanguage", "extensions", "favicons", "name", "publicUri" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "Name of the tenant." }, "favicons": { "description": "Favicon URLs returned for the tenant.", "$ref": "#/components/schemas/TenantConfigFaviconsWeb" }, "logoUrl": { "type": [ "null", "string" ], "description": "Optional logo URL." }, "appTitle": { "type": [ "null", "string" ], "description": "Optional browser/application title override." }, "status": { "description": "Tenant operational status.", "$ref": "#/components/schemas/TenantStatus" }, "purpose": { "description": "Tenant usage purpose.", "$ref": "#/components/schemas/TenantPurpose" }, "publicUri": { "minLength": 1, "type": "string", "description": "Effective public base URI used for end-user links." }, "defaultLanguage": { "minLength": 1, "type": "string", "description": "Default language configured for the tenant." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "List of languages available for the tenant." }, "extensions": { "type": "array", "items": { "type": "string" }, "description": "List of enabled extensions for this tenant." } }, "additionalProperties": false, "description": "Tenant core configuration response" }, "TenantConfigurationHistoryEntry": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "user": { "$ref": "#/components/schemas/TenantConfigurationHistoryUser" }, "files": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "TenantConfigurationHistoryPage": { "type": "object", "properties": { "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenantConfigurationHistoryEntry" } } }, "additionalProperties": false }, "TenantConfigurationHistoryUser": { "type": "object", "properties": { "userName": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } }, "additionalProperties": false }, "TenantConfigurationVersionInformation": { "type": "object", "properties": { "version": { "type": "string", "description": "Version of the configuration", "readOnly": true }, "files": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "description": "Returns version of each files of the configuration" }, "appliedMigrations": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "Version information related to a tenant configuration" }, "TenantDirectoryEntry": { "required": [ "tenantId" ], "type": "object", "properties": { "tenantId": { "type": "string" }, "status": { "$ref": "#/components/schemas/TenantDirectoryStatus" }, "purpose": { "$ref": "#/components/schemas/TenantDirectoryPurpose" } }, "additionalProperties": false }, "TenantDirectoryPurpose": { "enum": [ "demo", "test", "production" ], "type": "string" }, "TenantDirectoryStatus": { "enum": [ "onboarding", "active", "disabled" ], "type": "string" }, "TenantPurpose": { "enum": [ 1, 2, 3 ], "type": "integer", "description": "Intended usage context of the tenant.", "format": "int32" }, "TenantStatus": { "enum": [ 1, 2, 3 ], "type": "integer", "description": "Operational status of the tenant.", "format": "int32" }, "TenantUser": { "required": [ "email", "id" ], "type": "object", "properties": { "id": { "minLength": 1, "type": "string", "description": "User identifier." }, "email": { "minLength": 1, "type": "string", "description": "User email address." }, "name": { "type": [ "null", "string" ], "description": "Display name." }, "blocked": { "type": "boolean", "description": "True when the account is blocked." }, "lastLogin": { "type": [ "null", "string" ], "description": "Last login timestamp.", "format": "date-time" }, "tenantRole": { "type": [ "null", "string" ], "description": "Tenant role assigned to the user." } }, "additionalProperties": false, "description": "Tenant-scoped user representation." }, "TicketCanceledData": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/TicketData" } }, "additionalProperties": false }, "TicketCanceledDataWebhookRequest": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketCanceledData" } }, "additionalProperties": false }, "TicketCheckedData": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/TicketData" } }, "additionalProperties": false }, "TicketCheckedDataWebhookRequest": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketCheckedData" } }, "additionalProperties": false }, "TicketData": { "type": "object", "properties": { "token": { "type": "string" }, "identifier": { "type": "string" } }, "additionalProperties": false }, "TurnstileConfigurationResponse": { "required": [ "siteKey" ], "type": "object", "properties": { "siteKey": { "minLength": 1, "type": "string", "description": "Public site key configured for this tenant." }, "proofCookieValidityDurationSeconds": { "type": "integer", "description": "Duration in seconds the proof cookie remains valid. 0 means disabled.", "format": "int32" } }, "additionalProperties": false, "description": "Response body for Turnstile configuration." }, "TypeEnum": { "enum": [ "manual", "text", "qrcode", "pdf417", "aztec", "code128", "code39", "codabar", "ean8", "ean13", "itf14", "upca", "datamatrix", "nfc" ], "type": "string" }, "UpdateApiKeyRequest": { "required": [ "enabled" ], "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this key is active." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "New list of permission scopes. Use `[\"*\"]` for full access." } }, "additionalProperties": false, "description": "Request body to update an API key." }, "UpdateDevice": { "type": "object", "properties": { "name": { "type": "string", "description": "Device name." }, "description": { "type": [ "null", "string" ], "description": "Optional description." }, "isEnabled": { "type": "boolean", "description": "Whether the device should be enabled." } }, "additionalProperties": false, "description": "Payload to update a device." }, "UpdatePassDataOptions": { "type": "object", "properties": { "updateMetadata": { "type": "boolean", "description": "When true, recompute and persist pass metadata. Updating metadata is slower and is usually unnecessary for notification-only updates." }, "correlationId": { "type": [ "null", "string" ], "description": "Groups related updates under the same correlationId. Useful for batch updates (for example nightly jobs) to make retries and logs traceable." } }, "additionalProperties": false, "description": "Options used when updating passes." }, "UpdatePassData`1": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PassData" } ], "properties": { "passType": { "type": [ "null", "string" ], "description": "Optional pass type to convert the pass to." }, "updateMetadata": { "type": "boolean", "description": "Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update", "default": false, "deprecated": true }, "options": { "$ref": "#/components/schemas/TOptions" } }, "additionalProperties": false }, "UpdateRoleRequest": { "required": [ "permissions" ], "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string" }, "description": "New list of permission scopes granted to this role. Use [\"*\"] for full access." } }, "additionalProperties": false, "description": "Request body to update a role's permissions." }, "UpdateTenantConfigWebRequest": { "type": "object", "properties": { "logoUrl": { "type": [ "null", "string" ], "description": "Optional logo URL." }, "faviconUrl": { "type": [ "null", "string" ], "description": "Optional 48x48 favicon URL." }, "largeFaviconUrl": { "type": [ "null", "string" ], "description": "Optional 192x192 favicon URL. Set empty string to clear." }, "appleFaviconUrl": { "type": [ "null", "string" ], "description": "Optional Apple touch icon URL. Set empty string to clear." }, "appTitle": { "type": [ "null", "string" ], "description": "Optional application title override. Set empty string to clear." }, "defaultLanguage": { "type": [ "null", "string" ], "description": "Optional default language." }, "availableLanguages": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional available languages." }, "status": { "description": "Optional tenant status (global administrators only).", "$ref": "#/components/schemas/TenantStatus" }, "purpose": { "description": "Optional tenant purpose (global administrators only).", "$ref": "#/components/schemas/TenantPurpose" } }, "additionalProperties": false, "description": "Tenant core configuration patch request." }, "UpdateTenantUserRequest": { "required": [ "role" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "Updated display name." }, "role": { "minLength": 1, "type": "string", "description": "Updated tenant role." } }, "additionalProperties": false, "description": "Request payload for updating a tenant user." }, "UserInformation": { "type": "object", "properties": { "userName": { "type": "string" }, "password": { "type": "string" } }, "additionalProperties": false }, "WatchRequest": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "additionalProperties": false }, "WebClaim": { "type": "object", "properties": { "type": { "type": "string", "description": "claim type" }, "value": { "type": "string", "description": "Value" }, "valueType": { "type": [ "null", "string" ], "description": "optional value type" } }, "additionalProperties": false, "description": "Claim to generate JWT token for" }, "WebHook": { "required": [ "endpoint", "events" ], "type": "object", "properties": { "description": { "type": [ "null", "string" ], "description": "Description of the webhook" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Events to listen. Can ends with * to listen to more than one event" }, "endpoint": { "type": "string", "description": "Uri where a POST request will be made when the coresponding event happens.", "format": "uri" }, "enabled": { "type": "boolean", "description": "Determine if the webhook is enabled", "default": false } }, "additionalProperties": false }, "WebHookWithId": { "required": [ "id", "signatureSecret" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/WebHook" } ], "properties": { "id": { "minLength": 1, "type": "string", "description": "Unique identifier of this webhook" }, "signatureSecret": { "minLength": 1, "type": "string", "description": "Key used to sign the request.\nWhen The Wallet Crew platform sends a request it will add a X-NEOSTORE-SIGNATURE header with a hmacsha256 computed from the body content and this secret" } }, "additionalProperties": false }, "WebRedirectEntity": { "required": [ "id", "layout", "uri" ], "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the redirect" }, "layout": { "type": "string", "description": "Layout associated to this redirect" }, "creationDate": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64" } ], "description": "Creation date of this redirect Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings." }, "parameters": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional parameters to add to the layout url" }, "options": { "description": "Additional options for this redirect", "$ref": "#/components/schemas/WebRedirectOptions" }, "uri": { "type": "string", "description": "Short uri of the redirection uri" } }, "additionalProperties": false }, "WebRedirectOptions": { "type": "object", "properties": { "expirationDate": { "type": [ "null", "string" ], "description": "Date when the link will be expired. If a user access an expired link he will obtian a 404", "format": "date-time" }, "label": { "type": [ "null", "string" ], "description": "Optional friendly name of this redirect" }, "length": { "type": "integer", "description": "Size of the small uri, minLength is 6.", "format": "int32" } }, "additionalProperties": false } }, "parameters": { "tenantId": { "name": "tenantId", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } }, "securitySchemes": { "neo-customer": { "type": "http", "description": "a JWT token describing the customer", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "name": "X-API-KEY", "in": "header" }, "admin-bearer": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/", "scopes": { } } } } } }, "tags": [ { "name": "Barcode", "x-parent": "Tools" }, { "name": "Cache", "x-parent": "Tools" }, { "name": "Devices", "x-parent": "Tenant config" }, { "name": "EmailVerifier", "x-parent": "Tools" }, { "name": "Insights", "x-parent": "Tools" }, { "name": "Pass", "x-parent": "Pass Management" }, { "name": "Privilege", "x-parent": "Pass Management" }, { "name": "Receipt", "x-parent": "Internal" }, { "name": "Redirect", "x-parent": "Forms" }, { "name": "Scan", "x-parent": "Pass Management" }, { "name": "Scheduler", "x-parent": "Tenant config" }, { "name": "Secret", "x-parent": "Tenant config" }, { "name": "Store", "x-parent": "Forms" }, { "name": "Templates", "x-parent": "Advanced" }, { "name": "WebHook", "x-parent": "Tenant config" }, { "name": "Tenant", "x-parent": "Tenant config" }, { "name": "Warmup", "x-parent": "Internal" }, { "name": "ApiKeys", "x-parent": "Advanced" }, { "name": "Config", "x-parent": "Advanced" }, { "name": "AparteAdmin", "x-parent": "Advanced" }, { "name": "TurnstileAdmin", "x-parent": "Advanced" }, { "name": "Permissions", "x-parent": "Advanced" }, { "name": "Roles", "x-parent": "Advanced" }, { "name": "Users", "x-parent": "Advanced" }, { "name": "CachedContent", "x-parent": "Internal" }, { "name": "Advanced" }, { "name": "ApplePass", "x-parent": "Extensions" }, { "name": "GooglePass", "x-parent": "Extensions" }, { "name": "Extensions" }, { "name": "Internal" }, { "name": "Tools" }, { "name": "Tenant config" }, { "name": "Forms" }, { "name": "Pass Management" }, { "name": "Yurplan", "x-parent": "Extensions" }, { "name": "Logs", "x-parent": "Advanced" }, { "name": "Global", "x-parent": "Advanced" }, { "name": "TenantConfiguration", "x-parent": "Tenant config" }, { "name": "Public", "x-parent": "Internal" }, { "name": "Customer", "x-parent": "Forms" }, { "name": "Security", "x-parent": "Tenant config" }, { "name": "Cegid", "x-parent": "Extensions" }, { "name": "Secutix", "x-parent": "Extensions" }, { "name": "Actito", "x-parent": "Extensions" }, { "name": "Klaviyo", "x-parent": "Extensions" }, { "name": "SFMC", "x-parent": "Extensions" } ], "x-tagGroups": [{"name":"Pass Management","tags":["Pass","Privilege","Scan"]},{"name":"Forms","tags":["Customer","Redirect","Store"]},{"name":"Tenant config","tags":["Devices","Scheduler","Secret","Security","Tenant","TenantConfiguration","WebHook"]},{"name":"Tools","tags":["Barcode","Cache","EmailVerifier","Insights"]},{"name":"Internal","tags":["Admin","CachedContent","Public","Receipt","Warmup"]},{"name":"Extensions","tags":["Actito","ApplePass","Cegid","GooglePass","Klaviyo","Secutix","SFMC","Yurplan"]},{"name":"Advanced","tags":["Templates","ApiKeys","Config","AparteAdmin","TurnstileAdmin","Permissions","Roles","Users","Logs","Global"]}] }