openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Stayforge API",
    "version": "v1.1.11",
    "description": "API for managing cards within organizations. \n\n---\n\nAny Question? \n\n- [New issues](https://github.com/stayforge/Stayforge-API/issues).\n- [Documents](https://docs.stayforge.io/apis/stayforge-api/information)\n",
    "contact": {
      "name": "Stayforge Support",
      "email": "support@stayforge.co"
    },
    "license": {
      "name": "Stayforge API Terms of Service",
      "url": "https://docs.stayforge.io/apis/stayforge-api/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.stayforge.net",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Cards",
      "description": "Card management operations"
    },
    {
      "name": "Devices",
      "description": "Device management operations"
    },
    {
      "name": "APIKeys",
      "description": "API Key management operations (requires User's Access Token authentication)"
    },
    {
      "name": "Organizations",
      "description": "Organization management operations (requires User's Access Token authentication)"
    },
    {
      "name": "Tenants",
      "description": "Tenant management operations (requires User's Access Token authentication)"
    },
    {
      "name": "Account",
      "description": "Account-related operations (requires User's Access Token authentication)"
    },
    {
      "name": "Invites",
      "description": "Invitation code management operations (requires User's Access Token authentication)"
    }
  ],
  "paths": {
    "/v1/cards/{organization_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "summary": "List cards",
        "operationId": "ListCards",
        "tags": [
          "Cards"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          },
          {
            "name": "tenant_id",
            "in": "query",
            "required": false,
            "description": "Filter cards by tenant ID. Only cards that have at least one device belonging to this tenant will be returned.\nIf not provided, all cards in the organization are returned.\n",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of cards with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, pagination parameters, or validation error.\nError codes: `invalid_request`, `invalid_pagination`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_pagination": {
                    "value": {
                      "code": "invalid_pagination",
                      "message": "page number must be at least 1"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to access this resource"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a card",
        "operationId": "CreateCard",
        "tags": [
          "Cards"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/CardNumberQuery"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CardInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Card created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Card"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request body or validation error.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to create cards"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict - Card number already exists for this organization.\nError codes: `duplicate_card_number`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "duplicate_card_number": {
                    "value": {
                      "code": "duplicate_card_number",
                      "message": "Card number already exists for this organization"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity - Request is well-formed but contains semantic errors.\nError codes: `unprocessable_entity`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "unprocessable_entity": {
                    "value": {
                      "code": "unprocessable_entity",
                      "message": "Device validation failed"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `create_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "create_error": {
                    "value": {
                      "code": "create_error",
                      "message": "Failed to create card: failed to save card"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/cards/{organization_id}/{card_number}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/CardNumberPath"
        }
      ],
      "get": {
        "summary": "Card details",
        "operationId": "GetCard",
        "tags": [
          "Cards"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Card details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Card"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format or request parameters.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to access this card"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Card does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Card not found: card_number"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a card",
        "operationId": "UpdateCard",
        "tags": [
          "Cards"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CardUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Card"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request body or validation error.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to update cards"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Card does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Card not found: card_number"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict - Card number already exists for this organization.\nError codes: `duplicate_card_number`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "duplicate_card_number": {
                    "value": {
                      "code": "duplicate_card_number",
                      "message": "Card number already exists for this organization"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity - Request is well-formed but contains semantic errors.\nError codes: `unprocessable_entity`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "unprocessable_entity": {
                    "value": {
                      "code": "unprocessable_entity",
                      "message": "Device validation failed or invalid effective_at/invalid_at"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `update_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "update_error": {
                    "value": {
                      "code": "update_error",
                      "message": "Failed to update card: failed to update card"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a card",
        "operationId": "DeleteCard",
        "tags": [
          "Cards"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "400": {
            "description": "Bad request - Invalid path parameter format or request parameters.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to delete cards"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Card does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Card not found: card_number"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `delete_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "delete_error": {
                    "value": {
                      "code": "delete_error",
                      "message": "Failed to delete card: failed to delete card"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/devices/{organization_id}/{tenant_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        }
      ],
      "get": {
        "summary": "List devices",
        "operationId": "ListDevices",
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of devices with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, pagination parameters, or validation error.\nError codes: `invalid_request`, `invalid_pagination`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_pagination": {
                    "value": {
                      "code": "invalid_pagination",
                      "message": "page number must be at least 1"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to access this resource"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a device",
        "operationId": "CreateDevice",
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Device created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created device",
                "schema": {
                  "type": "string",
                  "example": "/v1/devices/org_xxxxxxxxxx/ten_xxxxxxxxxx/dev_xxxxxxxxxx"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, validation error, or tenant not found.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  },
                  "tenant_not_found": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions or organization_id mismatches.\nError codes: `insufficient_permissions`, `organization_id_mismatch`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to create devices"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict - Device ID already exists for this tenant.\nError codes: `duplicate_device_id`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "duplicate_device_id": {
                    "value": {
                      "code": "duplicate_device_id",
                      "message": "Device ID already exists for this tenant"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/devices/{organization_id}/{tenant_id}/{device_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        },
        {
          "$ref": "#/components/parameters/DeviceIdPath"
        }
      ],
      "get": {
        "summary": "Device details",
        "operationId": "GetDevice",
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Device details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "404": {
            "description": "Not found - Device does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Device not found: device_id"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a device",
        "operationId": "UpdateDevice",
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Device updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Device does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Device not found: device_id"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict - Device ID already exists for this tenant.\nError codes: `duplicate_device_id`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "duplicate_device_id": {
                    "value": {
                      "code": "duplicate_device_id",
                      "message": "Device ID already exists for this tenant"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a device",
        "operationId": "DeleteDevice",
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found - Device does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Device not found: device_id"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods (X-API-Key and Authorization Bearer token) are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/devices/sn/{sn}": {
      "parameters": [
        {
          "name": "sn",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": "Device serial number",
          "example": "SFVA78RABZ12345678"
        }
      ],
      "get": {
        "summary": "Get device information by serial number",
        "description": "Query device information from the SN database using a serial number.\nReturns model name, production date, and warranty information if available.\n",
        "operationId": "GetDeviceSN",
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Device information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceInfo"
                },
                "example": {
                  "sn": "SFVA78RABZ12345678",
                  "model_name": "VG-M350",
                  "production_date": "2025-01",
                  "warranty_expiry_date": "2027-01-31"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: invalid or missing API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key does not have required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "API key does not have permission to access this resource"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Serial number not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Serial number not found"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable - Both authentication methods are missing.\nError codes: `not_acceptable`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "value": {
                      "code": "not_acceptable",
                      "message": "Both authentication methods are missing"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "SN database service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_unavailable": {
                    "value": {
                      "code": "service_unavailable",
                      "message": "SN database service is not available"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/apikeys": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "post": {
        "summary": "Create an API key",
        "operationId": "CreateAPIKey",
        "tags": [
          "APIKeys"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/APIKeyInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created API key",
                "schema": {
                  "type": "string",
                  "example": "/v1/organizations/org_xxxxxxxxxx/apikeys/apikey_xxxxxxxxxx"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKeyCreate"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request body or validation error.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: json: cannot unmarshal string into Go struct field"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User does not have admin or owner role to manage API keys.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage API keys"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `create_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "create_error": {
                    "value": {
                      "code": "create_error",
                      "message": "Failed to create API key: failed to save API key"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "failed to initialize API key service: APIKEY_SIGNING_SECRET environment variable is not set"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List API keys",
        "operationId": "ListAPIKeys",
        "tags": [
          "APIKeys"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of API keys with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKeyListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format or pagination parameters.\nError codes: `invalid_pagination`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_pagination": {
                    "value": {
                      "code": "invalid_pagination",
                      "message": "page number must be at least 1"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User does not have admin or owner role to manage API keys.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage API keys"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `list_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_error": {
                    "value": {
                      "code": "list_error",
                      "message": "Failed to list API keys: failed to query API keys"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "failed to initialize API key service: APIKEY_SIGNING_SECRET environment variable is not set"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/apikeys/{apikey_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/APIKeyIdPath"
        }
      ],
      "get": {
        "summary": "Get API key details",
        "operationId": "GetAPIKey",
        "tags": [
          "APIKeys"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "API key details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKeyList"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format.\nError codes: `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User does not have admin or owner role to manage API keys.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage API keys"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - API key does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "API key not found: b9d0e02cb283477aa6e174053934b0e4"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "failed to initialize API key service: APIKEY_SIGNING_SECRET environment variable is not set"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update an API key",
        "operationId": "UpdateAPIKey",
        "tags": [
          "APIKeys"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/APIKeyUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "API key updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKeyList"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request body or validation error.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: json: cannot unmarshal string into Go struct field"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User does not have admin or owner role to manage API keys.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage API keys"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - API key does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "API key not found: b9d0e02cb283477aa6e174053934b0e4"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `update_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "update_error": {
                    "value": {
                      "code": "update_error",
                      "message": "Failed to update API key: failed to update API key"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "failed to initialize API key service: APIKEY_SIGNING_SECRET environment variable is not set"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete an API key",
        "operationId": "DeleteAPIKey",
        "tags": [
          "APIKeys"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "API key deleted successfully"
          },
          "400": {
            "description": "Bad request - Invalid path parameter format.\nError codes: `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User does not have admin or owner role to manage API keys.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage API keys"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - API key does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "API key not found: b9d0e02cb283477aa6e174053934b0e4"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `delete_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "delete_error": {
                    "value": {
                      "code": "delete_error",
                      "message": "Failed to delete API key: failed to delete API key"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "failed to initialize API key service: APIKEY_SIGNING_SECRET environment variable is not set"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/my_resources": {
      "get": {
        "summary": "List my resources",
        "operationId": "ListMyResources",
        "tags": [
          "Account"
        ],
        "description": "List all resources (organizations and tenants) that the current user belongs to.\nThis endpoint combines the functionality of listing organizations and tenants into a single call.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "List of user's resources (organizations and tenants)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MyResources"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/data/role": {
      "get": {
        "summary": "Get Organization Roles",
        "operationId": "GetOrganizationRoles",
        "tags": [
          "Organizations"
        ],
        "security": [],
        "description": "Retrieve available roles for organization members",
        "responses": {
          "200": {
            "description": "List of available organization roles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MemberRoleEnum"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request parameters.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations": {
      "get": {
        "summary": "List my organizations",
        "operationId": "ListMyOrganizations",
        "tags": [
          "Organizations",
          "Account"
        ],
        "description": "List the current user's active organizations. Archived organizations are excluded from this list.\nTo view archived organizations, use the `/organizations/archived` endpoint.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of active organizations with pagination (archived organizations are excluded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `list_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_error": {
                    "value": {
                      "code": "list_error",
                      "message": "Failed to list organizations: failed to query organizations"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a Organization",
        "operationId": "CreateOrganization",
        "tags": [
          "Organizations"
        ],
        "description": "Create a Organization including: **Name, Description, Custom Domain, Billing Address, Domain, Organization Id, Archive At, Metadata, Stripe Customer Id, Memberships, Apikey, Billing Info**\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Organization created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created organization",
                "schema": {
                  "type": "string",
                  "example": "/v1/organizations/org_xxxxxxxxxx"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `create_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "create_error": {
                    "value": {
                      "code": "create_error",
                      "message": "Failed to create organization: failed to save organization"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/archived": {
      "get": {
        "summary": "List my archived organizations",
        "operationId": "ListMyArchivedOrganizations",
        "tags": [
          "Organizations",
          "Account"
        ],
        "description": "List the current user's archived organizations.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of archived organizations with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/domain/check": {
      "parameters": [
        {
          "name": "domain",
          "in": "query",
          "required": true,
          "description": "Organization domain name to check. \n`*.stayforge.app`, domain prefix must be 4-64 characters, containing only lowercase letters and numbers.\n",
          "schema": {
            "type": "string",
            "minLength": 18,
            "maxLength": 78,
            "pattern": "^[a-z0-9]{4,64}\\.stayforge\\.app$",
            "example": "myorg123.stayforge.app"
          }
        }
      ],
      "get": {
        "summary": "Check whether the organization domain name is occupied",
        "operationId": "CheckOrganizationDomain",
        "tags": [
          "Organizations"
        ],
        "description": "`*.stayforge.app`, domain prefix must be 4-64 characters, containing only lowercase letters and numbers.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Domain availability check result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "available": {
                      "type": "boolean",
                      "description": "Whether the domain is available"
                    },
                    "domain": {
                      "type": "string",
                      "description": "The domain being checked"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid domain format or validation error.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid domain format: domain must match pattern ^[a-z0-9]{4,64}\\.stayforge\\.app$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "summary": "Get a Organization information",
        "operationId": "GetOrganization",
        "tags": [
          "Organizations"
        ],
        "description": "Get all information about the Organization, including: **Name, Description, Custom Domain, Billing Address, Domain, Organization Id, Archive At, Metadata, Stripe Customer Id, Memberships, Apikey, Billing Info**\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format.\nError codes: `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a Organization.",
        "operationId": "UpdateOrganization",
        "tags": [
          "Organizations"
        ],
        "description": "Update all or part of organization information.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Organization updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to update organization"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `update_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "update_error": {
                    "value": {
                      "code": "update_error",
                      "message": "Failed to update organization: failed to update organization"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a Organization",
        "operationId": "DeleteOrganization",
        "tags": [
          "Organizations"
        ],
        "description": "Permanently delete an organization. **Only archived organizations can be deleted.**\n**You must cancel all Subscriptions and delete all Tenants within the organization before deleting them.**\nOtherwise, payment will continue to be deducted after deletion.\nThis is a permanent operation and cannot be undone.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Organization deleted successfully"
          },
          "400": {
            "description": "Bad request - Organization is not archived.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Organization is not archived: only archived organizations can be deleted"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to delete organization"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `delete_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "delete_error": {
                    "value": {
                      "code": "delete_error",
                      "message": "Failed to delete organization: failed to delete organization"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/archive": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "post": {
        "summary": "Archive a Organization",
        "operationId": "ArchiveOrganization",
        "tags": [
          "Organizations"
        ],
        "description": "Archive an organization. This will set the archive_at field, marking the organization as archived.\nArchived organizations are excluded from the active organizations list but can be viewed via the archived organizations endpoint.\n\n**Important:** Before archiving, the system will check if the organization has any active Stripe subscriptions.\nIf active subscriptions are found, the archive operation will be rejected. You must cancel all subscriptions first.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization archived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Possible reasons:\n- Organization is already archived\n- Organization has active Stripe subscriptions (must cancel all subscriptions first)\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Organization has active Stripe subscriptions: must cancel all subscriptions first"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to archive organization"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Unarchive a Organization",
        "operationId": "UnarchiveOrganization",
        "tags": [
          "Organizations"
        ],
        "description": "Unarchive a previously archived organization. This will restore the organization to active status by clearing the archive_at field.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization unarchived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Organization is not archived.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Organization is not archived: cannot unarchive a non-archived organization"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to unarchive organization"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/memberships": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "summary": "List organization memberships",
        "operationId": "ListOrganizationMemberships",
        "tags": [
          "Organizations"
        ],
        "description": "List all memberships of the organization.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of organization memberships with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationMembershipListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `list_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_error": {
                    "value": {
                      "code": "list_error",
                      "message": "Failed to list organization memberships: failed to query memberships"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Add member to organization",
        "operationId": "CreateOrganizationMembership",
        "tags": [
          "Organizations"
        ],
        "description": "Add a new member to the organization. Requires admin or owner role.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationMembershipCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Membership created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created organization membership",
                "schema": {
                  "type": "string",
                  "example": "/v1/organizations/org_xxxxxxxxxx/memberships/auth0|xxxxxxxxxxxxxxx"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationMembership"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage organization memberships"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `create_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "create_error": {
                    "value": {
                      "code": "create_error",
                      "message": "Failed to create organization membership: failed to save membership"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/memberships/{member_sub}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/MemberSubPath"
        }
      ],
      "get": {
        "summary": "Get organization membership",
        "operationId": "GetOrganizationMembership",
        "tags": [
          "Organizations"
        ],
        "description": "Get a specific membership in the organization.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization membership information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationMembership"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format.\nError codes: `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization membership does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization membership not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update organization membership",
        "operationId": "UpdateOrganizationMembership",
        "tags": [
          "Organizations"
        ],
        "description": "Update a member's role in the organization. Requires admin or owner role.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationMembershipUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Membership updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationMembership"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to update organization membership"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization membership does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization membership not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `update_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "update_error": {
                    "value": {
                      "code": "update_error",
                      "message": "Failed to update organization membership: failed to update membership"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove member from organization",
        "operationId": "DeleteOrganizationMembership",
        "tags": [
          "Organizations"
        ],
        "description": "Remove a member from the organization. Requires admin or owner role. Cannot remove the last owner.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Membership deleted successfully"
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to delete organization membership"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization membership does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization membership not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `delete_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "delete_error": {
                    "value": {
                      "code": "delete_error",
                      "message": "Failed to delete organization membership: failed to delete membership"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "summary": "List tenants in Organization",
        "operationId": "ListOrganizationTenants",
        "tags": [
          "Organizations",
          "Tenants"
        ],
        "description": "List all tenants of organization.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of tenants with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format or pagination parameters.\nError codes: `invalid_pagination`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_pagination": {
                    "value": {
                      "code": "invalid_pagination",
                      "message": "page number must be at least 1"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `list_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_error": {
                    "value": {
                      "code": "list_error",
                      "message": "Failed to list tenants: failed to query tenants"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a tenant in Organization",
        "operationId": "CreateOrganizationTenant",
        "tags": [
          "Organizations",
          "Tenants"
        ],
        "description": "Create a tenant in organization.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tenant created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created tenant",
                "schema": {
                  "type": "string",
                  "example": "/v1/organizations/org_xxxxxxxxxx/tenants/ten_xxxxxxxxxx"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to create tenant"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Organization does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Organization not found: org_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `create_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "create_error": {
                    "value": {
                      "code": "create_error",
                      "message": "Failed to create tenant: failed to save tenant"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/invites": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "post": {
        "summary": "Create invitation code",
        "operationId": "CreateInvitationCode",
        "tags": [
          "Invites"
        ],
        "description": "Create a new invitation code for the specified organization.\n\n**Note:** Tenant-scoped invitations are planned and will be released in a future update.\n\n**Authentication:** User Access Token required.\n- User Token: Requires `admin` or `owner` role in the organization\n\n**Note:** The `owner` role cannot be assigned via invitation codes.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteCodeCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invitation code created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created invitation code",
                "schema": {
                  "type": "string",
                  "example": "/v1/organizations/org_xxx/invites/inv_abc123"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteCode"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format or request body (invalid target_role, etc.).\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Organization not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List invitation codes",
        "operationId": "ListInvitationCodes",
        "tags": [
          "Invites"
        ],
        "description": "Retrieve all invitation codes for the specified organization with pagination and status filtering.\n\n**Authentication:** User Access Token required.\n- User Token: Requires `admin` or `owner` role in the organization\n\n**Status Filtering:**\n- `active`: Active and usable codes (default)\n- `expired`: Codes that have passed their expiration date\n- `exhausted`: Codes that have reached their usage limit\n- `revoked`: Codes that have been deactivated\n- `all`: Return all codes regardless of status\n\nResults are sorted by `created_at` descending (newest first).\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          },
          {
            "$ref": "#/components/parameters/InviteStatusQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of invitation codes with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteCodeListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid query parameters (e.g., duplicate status values, invalid pagination)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Organization not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/invites/{invite_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/InviteIdPath"
        }
      ],
      "get": {
        "summary": "Get invitation code details",
        "operationId": "GetInvitationCode",
        "tags": [
          "Invites"
        ],
        "description": "Retrieve details of a specific invitation code.\n\n**Authentication:** User Access Token required.\n- User Token: Requires `admin` or `owner` role in the organization\n\n**Security:** The invitation code must belong to the organization specified in the path parameter.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Invitation code details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteCode"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format (e.g., malformed organization_id or invite_id).\nError codes: `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "invite_id must match pattern ^inv_[a-zA-Z0-9]+$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Invitation code or organization not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Revoke invitation code",
        "operationId": "RevokeInvitationCode",
        "tags": [
          "Invites"
        ],
        "description": "Revoke/deactivate a specific invitation code. The code cannot be used after revocation.\n\n**Authentication:** User Access Token required.\n- User Token: Requires `admin` or `owner` role in the organization\n\n**Security:** The invitation code must belong to the organization specified in the path parameter.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Invitation code revoked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteCode"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format (e.g., malformed organization_id or invite_id).\nError codes: `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "invite_id must match pattern ^inv_[a-zA-Z0-9]+$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Invitation code or organization not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/invites/join": {
      "post": {
        "summary": "Join organization by invitation code",
        "operationId": "JoinOrganizationByInvite",
        "tags": [
          "Invites"
        ],
        "description": "User joins an organization using an invitation code.\n\n**Authentication:** User Access Token required.\n\nThis endpoint requires a User Access Token to identify the specific user who is joining the organization.\n\n**Business Logic:**\n1. Validates the invitation code exists and is active\n2. Checks expiration and usage limits\n3. Verifies user is not already a member\n4. Adds user to organization membership with the target role\n5. Atomically increments usage counter\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteJoinRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully joined the organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteJoinResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid invitation code or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid UserAccessToken",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - User is already a member of this organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tenants/data/environment": {
      "get": {
        "summary": "Get Environment Types",
        "operationId": "GetTenantEnvironments",
        "tags": [
          "Tenants"
        ],
        "security": [],
        "description": "Retrieve available environment types for tenants",
        "responses": {
          "200": {
            "description": "List of available environment types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TenantEnvironmentEnum"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request parameters.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tenants/data/role": {
      "get": {
        "summary": "Get Tenant Roles",
        "operationId": "GetTenantRoles",
        "tags": [
          "Tenants"
        ],
        "security": [],
        "description": "Retrieve available roles for tenant members",
        "responses": {
          "200": {
            "description": "List of available tenant roles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MemberRoleEnum"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request parameters.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request parameters"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants/{tenant_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        }
      ],
      "get": {
        "summary": "Get a Tenant information",
        "operationId": "GetTenant",
        "tags": [
          "Tenants"
        ],
        "description": "Get all information about the Tenant, including: **Name, Description, Environment, Parent Organization, Tenant Id, Archive At, Metadata, Memberships, Apikey, Metrics**\n\n**Metrics:**\n- Real-time metrics (devices, cards) are cached for 15 minutes to improve performance\n- Some metrics fields may be null if the logging system is not yet implemented\n- Yesterday snapshot metrics require the logging system to be fully implemented\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantDetail"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a Tenant.",
        "operationId": "UpdateTenant",
        "tags": [
          "Tenants"
        ],
        "description": "Update all or part of tenant information.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tenant updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to update tenant"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `update_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "update_error": {
                    "value": {
                      "code": "update_error",
                      "message": "Failed to update tenant: failed to update tenant"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a Tenant",
        "operationId": "DeleteTenant",
        "tags": [
          "Tenants"
        ],
        "description": "Permanently delete a tenant. **Only archived tenants can be deleted.**\nThis is a permanent operation and cannot be undone.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Tenant deleted successfully"
          },
          "400": {
            "description": "Bad request - Tenant is not archived.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Tenant is not archived: only archived tenants can be deleted"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to delete tenant"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `delete_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "delete_error": {
                    "value": {
                      "code": "delete_error",
                      "message": "Failed to delete tenant: failed to delete tenant"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants/{tenant_id}/archive": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        }
      ],
      "post": {
        "summary": "Archive a Tenant",
        "operationId": "ArchiveTenant",
        "tags": [
          "Tenants"
        ],
        "description": "Archive a tenant. This will set the archive_at field, marking the tenant as archived.\nArchived tenants are excluded from the active tenants list.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant archived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Tenant is already archived.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Tenant is already archived"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to archive tenant"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Unarchive a Tenant",
        "operationId": "UnarchiveTenant",
        "tags": [
          "Tenants"
        ],
        "description": "Unarchive a previously archived tenant. This will restore the tenant to active status by clearing the archive_at field.\n",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant unarchived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantDetail"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Tenant is not archived.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Tenant is not archived: cannot unarchive a non-archived tenant"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to unarchive tenant"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants/{tenant_id}/memberships": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        }
      ],
      "get": {
        "summary": "List tenant memberships",
        "operationId": "ListTenantMemberships",
        "tags": [
          "Tenants"
        ],
        "description": "List all memberships of the tenant.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of tenant memberships with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantMembershipListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `list_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_error": {
                    "value": {
                      "code": "list_error",
                      "message": "Failed to list tenant memberships: failed to query memberships"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Add member to tenant",
        "operationId": "CreateTenantMembership",
        "tags": [
          "Tenants"
        ],
        "description": "Add a new member to the tenant. Requires admin or owner role.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantMembershipCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Membership created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created tenant membership",
                "schema": {
                  "type": "string",
                  "example": "/v1/organizations/org_xxxxxxxxxx/tenants/ten_xxxxxxxxxx/memberships/auth0|xxxxxxxxxxxxxxx"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantMembership"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to manage tenant memberships"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist or has been deleted.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found: ten_xxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `create_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "create_error": {
                    "value": {
                      "code": "create_error",
                      "message": "Failed to create tenant membership: failed to save membership"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants/{tenant_id}/memberships/{member_sub}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        },
        {
          "$ref": "#/components/parameters/MemberSubPath"
        }
      ],
      "get": {
        "summary": "Get tenant membership",
        "operationId": "GetTenantMembership",
        "tags": [
          "Tenants"
        ],
        "description": "Get a specific membership in the tenant.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant membership information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantMembership"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant membership does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant membership not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update tenant membership",
        "operationId": "UpdateTenantMembership",
        "tags": [
          "Tenants"
        ],
        "description": "Update a member's role in the tenant. Requires admin or owner role.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantMembershipUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Membership updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantMembership"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid path parameter format, request body, or validation error.\nError codes: `invalid_request`, `invalid_path_parameter`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_path_parameter": {
                    "value": {
                      "code": "invalid_path_parameter",
                      "message": "organization_id must match pattern ^org_[a-zA-Z0-9_-]+$"
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "code": "invalid_request",
                      "message": "Invalid request body: validation failed"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to update tenant membership"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant membership does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant membership not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `update_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "update_error": {
                    "value": {
                      "code": "update_error",
                      "message": "Failed to update tenant membership: failed to update membership"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove member from tenant",
        "operationId": "DeleteTenantMembership",
        "tags": [
          "Tenants"
        ],
        "description": "Remove a member from the tenant. Requires admin or owner role. Cannot remove the last owner.",
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Membership deleted successfully"
          },
          "401": {
            "description": "Unauthorized - Missing or invalid authentication token.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "authentication required: failed to get user info from context"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "you must have admin or owner role to delete tenant membership"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant membership does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant membership not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`, `delete_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "delete_error": {
                    "value": {
                      "code": "delete_error",
                      "message": "Failed to delete tenant membership: failed to delete membership"
                    }
                  },
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants/{tenant_id}/profiles": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        }
      ],
      "get": {
        "summary": "List All Tenant Profiles",
        "operationId": "GetTenantProfiles",
        "tags": [
          "Tenants"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "description": "Retrieve all device model profiles for a tenant",
        "responses": {
          "200": {
            "description": "List of all tenant profiles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "example": {
                    "VG-M350": {
                      "device_number": 999,
                      "http_address": "https://custom.example.com"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication required.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "code": "authentication_required",
                      "message": "Authentication token required"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_permissions": {
                    "value": {
                      "code": "insufficient_permissions",
                      "message": "You must have read permissions to view tenant profiles"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Tenant not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "service_error": {
                    "value": {
                      "code": "service_error",
                      "message": "Internal server error occurred"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/{organization_id}/tenants/{tenant_id}/profiles/{model}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/TenantIdPath"
        },
        {
          "$ref": "#/components/parameters/ModelPath"
        }
      ],
      "get": {
        "summary": "Get Tenant Profile by Model",
        "operationId": "GetTenantProfile",
        "tags": [
          "Tenants"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "description": "Retrieve a specific device model profile for a tenant",
        "responses": {
          "200": {
            "description": "Tenant profile for the specified model",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "example": {
                    "device_number": 999,
                    "http_address": "https://custom.example.com"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication required.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found - Profile not found for model.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "code": "not_found",
                      "message": "Profile not found for model: VG-M350"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Set or Update Tenant Profile",
        "operationId": "SetTenantProfile",
        "tags": [
          "Tenants"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "description": "Set or update a device model profile for a tenant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "description": "Profile configuration object",
                "example": {
                  "device_number": 999,
                  "http_address": "https://custom.example.com"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile set successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid profile data.\nError codes: `invalid_request`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication required.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found - Tenant does not exist.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete Tenant Profile",
        "operationId": "DeleteTenantProfile",
        "tags": [
          "Tenants"
        ],
        "security": [
          {
            "UserAccessToken": []
          }
        ],
        "description": "Delete a device model profile from a tenant",
        "responses": {
          "204": {
            "description": "Profile deleted successfully"
          },
          "401": {
            "description": "Unauthorized - Authentication required.\nError codes: `authentication_required`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks required permissions.\nError codes: `insufficient_permissions`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found - Profile not found for model.\nError codes: `not_found`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Service or database error occurred.\nError codes: `service_error`\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API Key authentication using X-API-Key header.\nAPI keys must be prefixed with `sk_live_`.\nAll API keys are organization-level only.\nInclude the API key in the X-API-Key header as: `X-API-Key: <api_key>`\nGet your API key from the [dash.stayforge.io/settings/apikeys](https://dash.stayforge.io/settings/apikeys).\n"
      },
      "UserAccessToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "User's Access Token authentication using Bearer token.\nInclude the token in the Authorization header as: `Authorization: Bearer <token>`\nThis authentication method is used for API Key management endpoints.\nUsers must have admin or owner role in the organization to manage API keys.\n"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable error message describing what went wrong",
            "example": "API key not found: b9d0e02cb283477aa6e174053934b0e4"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code for programmatic error handling.\nCommon error codes:\n- `authentication_required`: Missing or invalid authentication token (401)\n- `insufficient_permissions`: User lacks required permissions (403)\n- `organization_id_mismatch`: Organization ID in path does not match API key organization (403)\n- `not_found`: Requested resource not found (404)\n- `invalid_request`: Request body validation failed (400)\n- `invalid_pagination`: Pagination parameters are invalid (400)\n- `create_error`: Failed to create resource (500)\n- `update_error`: Failed to update resource (500)\n- `delete_error`: Failed to delete resource (500)\n- `list_error`: Failed to list resources (500)\n- `service_error`: Internal service error (500)\n",
            "example": "not_found"
          },
          "details": {
            "type": "object",
            "description": "Additional error details (optional, structure varies by error type)",
            "additionalProperties": true
          }
        }
      },
      "MemberRoleEnum": {
        "type": "string",
        "enum": [
          "read",
          "read/write",
          "admin",
          "owner"
        ],
        "description": "Available roles for resource members (organizations and tenants)"
      },
      "Organization": {
        "$ref": "#/components/schemas/OrganizationDetail"
      },
      "OrganizationSummary": {
        "type": "object",
        "required": [
          "organization_id",
          "name",
          "domain"
        ],
        "properties": {
          "organization_id": {
            "type": "string",
            "readOnly": true,
            "description": "Organization ID",
            "example": "org_xxxxxxxxxx"
          },
          "name": {
            "type": "string",
            "minLength": 4,
            "maxLength": 64,
            "description": "Name of the organization.",
            "example": "Psychologist, forensic Hotel"
          },
          "domain": {
            "type": "string",
            "minLength": 18,
            "maxLength": 78,
            "pattern": "^[a-z0-9]{4,64}\\.stayforge\\.app$",
            "description": "Domain of the organization.\nDomain prefix must be 4-64 characters, containing only lowercase letters and numbers.\n",
            "example": "myorg123.stayforge.app"
          },
          "archive_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true,
            "description": "Archive timestamp. If null, the organization is active."
          },
          "member_count": {
            "type": "integer",
            "nullable": true,
            "description": "Total number of members (optional, may not be included in all list views)",
            "example": 5
          },
          "active_apikey_count": {
            "type": "integer",
            "nullable": true,
            "description": "Number of active API keys (optional, may not be included in all list views)",
            "example": 3
          }
        }
      },
      "OrganizationDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/OrganizationSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "maxLength": 1024,
                "nullable": true,
                "description": "Description of the organization"
              },
              "custom_domain": {
                "type": "string",
                "nullable": true,
                "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$",
                "format": "hostname",
                "description": "Custom domain of the organization"
              },
              "billing_address": {
                "$ref": "#/components/schemas/BillingAddress",
                "nullable": true
              },
              "billing_account_id": {
                "type": "string",
                "nullable": true,
                "readOnly": true
              },
              "metadata": {
                "$ref": "#/components/schemas/Metadata"
              },
              "memberships": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OrganizationMembership"
                },
                "maxItems": 100
              },
              "apikey": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/APIKeyInDB"
                },
                "maxItems": 50
              },
              "billing_info": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "nullable": true
              }
            }
          }
        ]
      },
      "OrganizationInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 4,
            "maxLength": 64,
            "description": "Name of the organization.",
            "example": "Psychologist, forensic Hotel"
          },
          "description": {
            "type": "string",
            "maxLength": 1024,
            "nullable": true,
            "description": "Description of the organization",
            "example": "Source common easy none which study north Democrat as when agent hundred stay."
          },
          "custom_domain": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$",
            "format": "hostname",
            "description": "Custom domain of the organization",
            "example": "your-domain.com"
          },
          "billing_address": {
            "$ref": "#/components/schemas/BillingAddress",
            "nullable": true,
            "description": "Billing address of the organization",
            "example": {
              "line1": "6530 Mcclain Crescent Apt. 135",
              "line2": "Apt. 338",
              "city": "East Isaac",
              "state": "Tennessee",
              "postal_code": "94141",
              "country": "US",
              "phone": "311-747-0060x45985",
              "email": "davidthompson@example.com"
            }
          },
          "domain": {
            "type": "string",
            "minLength": 18,
            "maxLength": 78,
            "pattern": "^[a-z0-9]{4,64}\\.stayforge\\.app$",
            "nullable": true,
            "description": "Domain of the organization. If not provided, will be auto-generated based on organization_id.\nDomain prefix must be 4-64 characters, containing only lowercase letters and numbers.\n",
            "example": "myorg123.stayforge.app"
          }
        }
      },
      "OrganizationUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 4,
            "maxLength": 64,
            "description": "Name of the organization.",
            "example": "Psychologist, forensic Hotel"
          },
          "description": {
            "type": "string",
            "maxLength": 1024,
            "nullable": true,
            "description": "Description of the organization",
            "example": "Source common easy none which study north Democrat as when agent hundred stay."
          },
          "custom_domain": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$",
            "format": "hostname",
            "description": "Custom domain of the organization",
            "example": "your-domain.com"
          },
          "billing_address": {
            "$ref": "#/components/schemas/BillingAddress",
            "nullable": true,
            "description": "Billing address of the organization",
            "example": {
              "line1": "6530 Mcclain Crescent Apt. 135",
              "line2": "Apt. 338",
              "city": "East Isaac",
              "state": "Tennessee",
              "postal_code": "94141",
              "country": "US",
              "phone": "311-747-0060x45985",
              "email": "davidthompson@example.com"
            }
          }
        }
      },
      "OrganizationRoleEnum": {
        "$ref": "#/components/schemas/MemberRoleEnum"
      },
      "OrganizationMembership": {
        "type": "object",
        "required": [
          "organization_id",
          "member_sub",
          "role"
        ],
        "properties": {
          "organization_id": {
            "type": "string",
            "readOnly": true,
            "description": "Organization ID.",
            "example": "org_xxxxxxxxxx"
          },
          "member_sub": {
            "type": "string",
            "description": "Member sub from auth0",
            "example": "auth0|xxxxxxxxxxxxxxx"
          },
          "role": {
            "$ref": "#/components/schemas/MemberRoleEnum",
            "description": "Role of the member.",
            "example": "admin"
          },
          "profile": {
            "$ref": "#/components/schemas/UserInfo",
            "nullable": true,
            "description": "Profile of the member. Only included when explicitly requested."
          }
        }
      },
      "OrganizationMembershipCreate": {
        "type": "object",
        "required": [
          "member_sub",
          "role"
        ],
        "properties": {
          "member_sub": {
            "type": "string",
            "description": "Member sub from auth0",
            "example": "auth0|xxxxxxxxxxxxxxx"
          },
          "role": {
            "$ref": "#/components/schemas/MemberRoleEnum",
            "description": "Role of the member.",
            "example": "admin"
          }
        },
        "description": "Request model for creating organization membership"
      },
      "OrganizationMembershipUpdate": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "$ref": "#/components/schemas/MemberRoleEnum",
            "description": "New role of the member.",
            "example": "admin"
          }
        },
        "description": "Request model for updating organization membership"
      },
      "OrganizationMembershipResponse": {
        "$ref": "#/components/schemas/OrganizationMembership"
      },
      "OrganizationListResponse": {
        "type": "object",
        "required": [
          "organizations",
          "pagination"
        ],
        "properties": {
          "organizations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganizationSummary"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "OrganizationMembershipListResponse": {
        "type": "object",
        "required": [
          "memberships",
          "pagination"
        ],
        "properties": {
          "memberships": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganizationMembership"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "Tenant": {
        "$ref": "#/components/schemas/TenantDetail"
      },
      "TenantSummary": {
        "type": "object",
        "required": [
          "tenant_id",
          "name"
        ],
        "properties": {
          "tenant_id": {
            "type": "string",
            "readOnly": true,
            "description": "Tenant ID",
            "example": "ten_xxxxxxxxxx"
          },
          "name": {
            "type": "string",
            "minLength": 4,
            "maxLength": 64,
            "description": "Name of the tenant.",
            "example": "Lobbyist Hotel"
          },
          "environment": {
            "$ref": "#/components/schemas/TenantEnvironmentEnum",
            "description": "Environment of the tenant",
            "default": "development",
            "example": "development"
          },
          "archive_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true,
            "description": "Archive timestamp. If null, the tenant is active."
          },
          "member_count": {
            "type": "integer",
            "nullable": true,
            "description": "Total number of members (optional, may not be included in all list views)",
            "example": 3
          },
          "active_apikey_count": {
            "type": "integer",
            "nullable": true,
            "description": "Number of active API keys (optional, may not be included in all list views)",
            "example": 2
          }
        }
      },
      "TenantDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TenantSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "maxLength": 1024,
                "nullable": true
              },
              "parent_organization": {
                "type": "string",
                "nullable": true,
                "readOnly": true
              },
              "metadata": {
                "$ref": "#/components/schemas/Metadata"
              },
              "profiles": {
                "type": "object",
                "nullable": true,
                "additionalProperties": {
                  "type": "object",
                  "additionalProperties": true
                },
                "description": "Device model default profiles. Map of model name to profile configuration.\nEach model can have a default profile that applies to all devices of that model in this tenant.\n",
                "example": {
                  "VG-M350": {
                    "device_number": 999,
                    "http_address": "https://custom.example.com/api"
                  }
                }
              },
              "memberships": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TenantMembership"
                },
                "maxItems": 100
              },
              "apikey": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/APIKeyInDB"
                },
                "maxItems": 50
              },
              "metrics": {
                "$ref": "#/components/schemas/TenantMetrics",
                "nullable": true
              }
            }
          }
        ]
      },
      "TenantRoleEnum": {
        "$ref": "#/components/schemas/MemberRoleEnum"
      },
      "TenantListResponse": {
        "type": "object",
        "required": [
          "tenants",
          "pagination"
        ],
        "properties": {
          "tenants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TenantSummary"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "TenantMembershipListResponse": {
        "type": "object",
        "required": [
          "memberships",
          "pagination"
        ],
        "properties": {
          "memberships": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TenantMembership"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "InviteCode": {
        "type": "object",
        "required": [
          "id",
          "code",
          "scope_type",
          "scope_id",
          "target_role",
          "max_uses",
          "current_uses",
          "is_active",
          "created_by",
          "created_at",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the invitation (format: inv_xxxxxxxxxx)",
            "example": "inv_abc123xyz",
            "readOnly": true
          },
          "code": {
            "type": "string",
            "minLength": 9,
            "maxLength": 9,
            "pattern": "^[A-Z0-9]{4}-[A-Z0-9]{4}$",
            "description": "Unique random invitation code",
            "example": "GX82-K9LP",
            "readOnly": true
          },
          "scope_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InviteScopeTypeEnum"
              }
            ],
            "description": "Type of scope this invitation applies to (currently only ORGANIZATION)",
            "example": "ORGANIZATION"
          },
          "scope_id": {
            "type": "string",
            "description": "ID of the scope (organization_id or tenant_id)",
            "example": "org_xxxxxxxxxx"
          },
          "target_role": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InviteRoleEnum"
              }
            ],
            "description": "Role assigned to users who accept this invitation",
            "example": "read/write"
          },
          "max_uses": {
            "type": "integer",
            "minimum": 0,
            "description": "Maximum number of times this code can be used (0 = unlimited)",
            "example": 10
          },
          "current_uses": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of times this code has been used",
            "example": 3,
            "readOnly": true
          },
          "is_active": {
            "type": "boolean",
            "description": "Whether the invitation code is active and can be used",
            "default": true,
            "example": true
          },
          "created_by": {
            "type": "string",
            "description": "User sub of the creator (from UserAccessToken or API Key's user_sub)",
            "example": "auth0|xxxxxxxxxxxxxxx",
            "readOnly": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Expiration timestamp (null = never expires)",
            "example": "2026-02-01T00:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp",
            "readOnly": true,
            "example": "2026-01-03T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp",
            "readOnly": true,
            "example": "2026-01-03T15:30:00Z"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InviteStatusEnum"
              }
            ],
            "description": "Computed status of the invitation code (read-only, calculated on read).\n- active: is_active=true AND not expired AND not exhausted\n- expired: is_active=true AND expires_at <= now\n- exhausted: is_active=true AND max_uses > 0 AND current_uses >= max_uses\n- revoked: is_active=false\n",
            "readOnly": true,
            "example": "active"
          }
        }
      },
      "InviteCodeCreate": {
        "type": "object",
        "required": [
          "target_role"
        ],
        "properties": {
          "target_role": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InviteRoleEnum"
              }
            ],
            "description": "Role assigned to users who accept this invitation",
            "example": "read/write"
          },
          "max_uses": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Maximum number of times this code can be used (0 = unlimited)",
            "example": 10
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Expiration timestamp (null = never expires)",
            "example": "2026-02-01T00:00:00Z"
          }
        }
      },
      "InviteCodeListResponse": {
        "type": "object",
        "required": [
          "invites",
          "pagination"
        ],
        "properties": {
          "invites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InviteCode"
            },
            "description": "List of invitation codes"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "InviteJoinRequest": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "minLength": 9,
            "maxLength": 9,
            "pattern": "^[A-Z0-9]{4}-[A-Z0-9]{4}$",
            "description": "The invitation code to use",
            "example": "GX82-K9LP"
          }
        }
      },
      "InviteJoinResponse": {
        "type": "object",
        "required": [
          "organization_id",
          "member_sub",
          "role",
          "joined_at"
        ],
        "properties": {
          "organization_id": {
            "type": "string",
            "description": "Organization ID that the user joined",
            "example": "org_xxxxxxxxxx"
          },
          "member_sub": {
            "type": "string",
            "description": "User sub of the member who joined",
            "example": "auth0|xxxxxxxxxxxxxxx"
          },
          "role": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InviteRoleEnum"
              }
            ],
            "description": "Role assigned to the new member",
            "example": "read/write"
          },
          "joined_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the user joined",
            "example": "2026-01-03T16:00:00Z"
          }
        }
      },
      "InviteRoleEnum": {
        "type": "string",
        "enum": [
          "read",
          "read/write",
          "admin"
        ],
        "description": "Role assigned to users who accept invitations.\nNote: This uses a dedicated enum that excludes `owner`. The `owner` role cannot be assigned via invitation codes for security reasons.\n",
        "example": "read/write"
      },
      "InviteStatusEnum": {
        "type": "string",
        "enum": [
          "active",
          "expired",
          "exhausted",
          "revoked"
        ],
        "description": "Computed status of the invitation code",
        "example": "active"
      },
      "InviteScopeTypeEnum": {
        "type": "string",
        "enum": [
          "ORGANIZATION",
          "TENANT"
        ],
        "description": "Type of scope this invitation applies to.\nTenant-scoped invitations are planned and will be released in a future update.\n",
        "example": "ORGANIZATION"
      },
      "CardProperties": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string",
            "nullable": true,
            "minLength": 3,
            "maxLength": 64,
            "description": "Descriptive name for the card."
          },
          "devices": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
            },
            "maxItems": 1000,
            "example": [
              "device-001",
              "device-002"
            ],
            "description": "List of `device_id` values associated with the card (max 1000 per request).\nEach device_id must be registered within the organization.\nDevice IDs must contain only lowercase letters, numbers, or hyphens (-). Cannot start or end with a hyphen.\n"
          },
          "effective_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Effective time (when the card becomes active).\nMust be the current time or a future time.\n**⚠️Default: `UTC`**, recommended to use the format `2025-02-16T12:00:00+01:00` to ensure the correct time zone.\nAbout ISO 8601: https://en.wikipedia.org/wiki/ISO_8601\n"
          },
          "invalid_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Invalidation time (when the card becomes invalid/expires).\nMust be the current time or a future time.\n**⚠️Default: `UTC`**, recommended to use the format `2025-02-16T12:00:00+01:00` to ensure the correct time zone.\nAbout ISO 8601: https://en.wikipedia.org/wiki/ISO_8601\n"
          },
          "barcode_type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "qrcode",
              "aztec",
              "pdf417",
              "code128"
            ],
            "default": "qrcode",
            "description": "Barcode format for the card. Defaults to 'qrcode' if not specified.\nSupported formats:\n- qrcode: QR Code (2D, widely supported)\n- aztec: Aztec Code (2D, compact for mobile ticketing)\n- pdf417: PDF417 (2D, common in boarding passes)\n- code128: Code 128 (1D barcode)\n"
          },
          "barcode_format": {
            "type": "string",
            "nullable": true,
            "enum": [
              "png",
              "jpg",
              "webp"
            ],
            "description": "Preferred image format for the barcode URL.\nIf not specified, format is auto-detected based on browser Accept header\n(WebP for modern browsers, PNG for older browsers).\n\nSupported formats:\n- png: PNG format (1-3KB, universal compatibility)\n- jpg: JPEG format (1-2KB, smallest file size)\n- webp: WebP format (0.8-2KB, best compression, modern browsers)\n\nNote: Users can override this by adding file extension to the URL\n(e.g., .jpg, .png, .webp, case-insensitive).\n",
            "example": "webp"
          }
        }
      },
      "CardNumberSchema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 256,
        "pattern": "^[a-zA-Z0-9_-]+$",
        "description": "Card No. (must be unique within your organization)."
      },
      "Card": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CardProperties"
          },
          {
            "type": "object",
            "required": [
              "id",
              "organization_id",
              "number"
            ],
            "properties": {
              "id": {
                "type": "string",
                "readOnly": true,
                "description": "Card ID (system-generated)."
              },
              "organization_id": {
                "type": "string",
                "readOnly": true,
                "description": "Organization ID that owns this card (system-managed)."
              },
              "number": {
                "$ref": "#/components/schemas/CardNumberSchema"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "readOnly": true,
                "description": "Card creation timestamp (system-managed, UTC timezone)."
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "readOnly": true,
                "description": "Card last update timestamp (system-managed, UTC timezone)."
              },
              "barcode_url": {
                "type": "string",
                "readOnly": true,
                "nullable": true,
                "description": "URL to access the barcode/QR code image.\n\n**Format Selection**:\n1. No extension (recommended): Auto-detects format via Accept header\n   - Modern browsers → WebP (0.8-2KB, smallest)\n   - Older browsers → PNG (1-3KB, compatible)\n2. Explicit extension: .png, .jpg, .webp (case-insensitive)\n\nThe type parameter in the URL matches the barcode_type stored for this card.\nIf barcode_format is specified, the URL will include the extension.\n",
                "example": "https://api.stayforge.net/g/barcode_img/generate/CARD123456?type=qrcode"
              }
            }
          }
        ]
      },
      "Pagination": {
        "type": "object",
        "required": [
          "page",
          "limit",
          "total",
          "total_pages"
        ],
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current page number",
            "example": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Number of items per page",
            "example": 20
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of items",
            "example": 100
          },
          "total_pages": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of pages",
            "example": 5
          },
          "has_next": {
            "type": "boolean",
            "description": "Whether there is a next page",
            "example": true
          },
          "has_prev": {
            "type": "boolean",
            "description": "Whether there is a previous page",
            "example": false
          },
          "next_page_url": {
            "type": "string",
            "nullable": true,
            "description": "URL for the next page (includes page and limit as query parameters)",
            "example": "/v1/cards/org_123?page=2&limit=20"
          },
          "prev_page_url": {
            "type": "string",
            "nullable": true,
            "description": "URL for the previous page (includes page and limit as query parameters)",
            "example": "/v1/cards/org_123?page=1&limit=20"
          },
          "first_page_url": {
            "type": "string",
            "description": "URL for the first page (includes page=1 and limit as query parameters)",
            "example": "/v1/cards/org_123?page=1&limit=20"
          },
          "last_page_url": {
            "type": "string",
            "description": "URL for the last page (includes last page number and limit as query parameters)",
            "example": "/v1/cards/org_123?page=5&limit=20"
          }
        }
      },
      "CardListResponse": {
        "type": "object",
        "required": [
          "cards",
          "pagination"
        ],
        "properties": {
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Card"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "CardInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CardProperties"
          }
        ]
      },
      "CardUpdate": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CardProperties"
          }
        ]
      },
      "DeviceStatus": {
        "type": "string",
        "enum": [
          "active",
          "paused"
        ],
        "description": "Device status. Only devices with status \"active\" will be billed.\n- active: Device is active and will be billed\n- paused: Device is paused and will not be billed\n"
      },
      "Metadata": {
        "type": "object",
        "nullable": true,
        "additionalProperties": true,
        "maxProperties": 64,
        "description": "Metadata as flexible key-value pairs supporting any JSON value type.\n\nConstraints:\n- Keys must match pattern: ^[a-z][a-z0-9_]{0,31}$ (lowercase start, 1-32 chars, alphanumeric+underscore)\n- Maximum 64 key-value pairs (maxProperties)\n- Maximum JSON depth: 4 levels\n- Maximum total size: 4096 bytes (enforced at application layer)\n- All values must be valid JSON\n\nExample:\n{\n  \"environment\": \"production\",\n  \"team\": \"backend\",\n  \"config\": {\n    \"retry_count\": 3,\n    \"timeout_ms\": 5000\n  }\n}\n"
      },
      "DeviceProperties": {
        "type": "object",
        "properties": {
          "device_id": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
            "description": "Device identifier (must be unique within the tenant).\nMust contain only lowercase letters, numbers, or hyphens (-). Cannot start or end with a hyphen.\n"
          },
          "sn": {
            "type": "string",
            "nullable": true,
            "description": "Serial number of the device."
          },
          "display_name": {
            "type": "string",
            "nullable": true,
            "minLength": 3,
            "maxLength": 128,
            "description": "Human-readable name for the device."
          },
          "price_id": {
            "type": "string",
            "nullable": true,
            "description": "Stripe price ID for billing purposes."
          },
          "status": {
            "$ref": "#/components/schemas/DeviceStatus"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "profile": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Device-specific profile configuration override.\nIf set, overrides tenant-level and project-level defaults for this device.\nSet to null to clear and fall back to tenant/project defaults.\n"
          }
        }
      },
      "DeviceModelEnum": {
        "type": "string",
        "enum": [
          "VG-M350"
        ],
        "description": "Available device models.\nCurrently only VG-M350 is supported. More models will be added in the future.\n"
      },
      "Device": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DeviceProperties"
          },
          {
            "type": "object",
            "required": [
              "id",
              "tenant_id",
              "model"
            ],
            "properties": {
              "id": {
                "type": "string",
                "readOnly": true,
                "description": "Unique device identifier (system-generated)."
              },
              "tenant_id": {
                "type": "string",
                "readOnly": true,
                "description": "Tenant identifier that owns this device (system-managed)."
              },
              "device_id": {
                "type": "string",
                "nullable": true,
                "minLength": 1,
                "maxLength": 256,
                "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
                "description": "Device identifier (must be unique within the tenant).\nMust contain only lowercase letters, numbers, or hyphens (-). Cannot start or end with a hyphen.\nReturns null if not set.\n"
              },
              "model": {
                "$ref": "#/components/schemas/DeviceModelEnum",
                "readOnly": true,
                "description": "Device model. This field is not stored in the database and is dynamically computed in API responses.\nFuture: Will be determined by querying product database using serial number.\n"
              },
              "resolved_profile": {
                "type": "object",
                "readOnly": true,
                "additionalProperties": true,
                "description": "Effective profile configuration after applying three-level fallback logic:\n1. Device-specific profile (device.profile)\n2. Tenant model default (tenant.profiles[model])\n3. Default configuration managed by Stayforge\n\nAlways present — returns HTTP 500 if no profile can be resolved at any level.\nThis field is computed dynamically and cannot be set directly.\n"
              },
              "signed_config": {
                "type": "string",
                "nullable": true,
                "readOnly": true,
                "description": "Signed configuration string for VGuang device deployment.\nFormat: ___VBAR_CONFIG_V1.1.0___{config_params}--{signature}\n\nThis field is computed dynamically by calling the VGUANG-Tools microservice\nwith the device's resolved_profile. The microservice signs the configuration\nand returns a deployment-ready string.\n\nCached for 4 minutes to optimize performance and reduce microservice load.\nReturns null if resolved_profile is not available or microservice fails.\n",
                "example": "___VBAR_CONFIG_V1.1.0___{w_mode=1,ochannel=64,nochannel=64}--wgQKdybMgLYbhO1S1Sf1Vg=="
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "readOnly": true,
                "description": "Device creation timestamp (system-managed, UTC timezone)."
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "readOnly": true,
                "description": "Device last update timestamp (system-managed, UTC timezone)."
              }
            }
          }
        ]
      },
      "DeviceListResponse": {
        "type": "object",
        "required": [
          "devices",
          "pagination"
        ],
        "properties": {
          "devices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Device"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "DeviceInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DeviceProperties"
          }
        ],
        "type": "object",
        "required": [
          "device_id",
          "sn"
        ],
        "properties": {
          "device_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
            "description": "Device identifier (must be unique within the tenant).\nMust contain only lowercase letters, numbers, or hyphens (-). Cannot start or end with a hyphen.\nThis field is required when creating a device.\n"
          },
          "sn": {
            "type": "string",
            "description": "Serial number of the device. This field is required when creating a device."
          }
        }
      },
      "DeviceUpdate": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DeviceProperties"
          },
          {
            "type": "object",
            "properties": {
              "device_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "nullable": true,
                "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
                "description": "Device identifier (must be unique within the tenant).\nMust contain only lowercase letters, numbers, or hyphens (-). Cannot start or end with a hyphen.\n"
              },
              "sn": {
                "type": "string",
                "nullable": true
              },
              "display_name": {
                "type": "string",
                "nullable": true,
                "minLength": 3,
                "maxLength": 128
              },
              "price_id": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "$ref": "#/components/schemas/DeviceStatus"
              },
              "metadata": {
                "$ref": "#/components/schemas/Metadata"
              }
            }
          }
        ]
      },
      "DeviceInfo": {
        "type": "object",
        "required": [
          "sn",
          "model_name"
        ],
        "properties": {
          "sn": {
            "type": "string",
            "description": "Device serial number",
            "example": "SFVA78RABZ12345678"
          },
          "model_name": {
            "type": "string",
            "description": "Device model name",
            "example": "VG-M350"
          },
          "production_date": {
            "type": "string",
            "nullable": true,
            "description": "Production date (YYYY-MM format)",
            "example": "2025-01"
          },
          "warranty_expiry_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Warranty expiry date (ISO 8601 date format)",
            "example": "2027-01-31"
          }
        }
      },
      "APIKeyStatus": {
        "type": "string",
        "enum": [
          "active",
          "suspended"
        ],
        "description": "Status of the API key"
      },
      "APIKeyUpdate": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 4,
            "maxLength": 128,
            "description": "Name/description of the API key",
            "example": "Production API Key"
          },
          "permissions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50,
            "description": "Allowed Permissions (scope:role format) for the API key (max 50)",
            "example": [
              "cards:read",
              "cards:write"
            ]
          },
          "allowed_ips": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "description": "Allowed IP ranges (CIDR) for this API key (max 100)",
            "example": [
              "0.0.0.0/0",
              "32.68.123.64/32"
            ]
          },
          "allowed_tenants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "description": "List of tenant IDs that this API key can access (max 100).\nIf empty or null, the API key can access all tenants within the organization.\nIf specified, the API key can only access the listed tenants.\n",
            "example": [
              "ten_xxxxxxxxxx",
              "ten_yyyyyyyyyy"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/APIKeyStatus",
            "description": "Status of the API key"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Tags for the API key (max 20)",
            "example": [
              "production",
              "backend"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "APIKeyInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/APIKeyUpdate"
          },
          {
            "type": "object",
            "properties": {
              "ttl": {
                "type": "integer",
                "nullable": true,
                "description": "TTL of the API key in seconds. If not set, the default TTL is used.",
                "example": 3600
              }
            }
          }
        ]
      },
      "APIKeyInDB": {
        "allOf": [
          {
            "$ref": "#/components/schemas/APIKeyInput"
          },
          {
            "type": "object",
            "required": [
              "apikey_id",
              "organization_id",
              "created_at",
              "secret_masked",
              "is_suspended"
            ],
            "properties": {
              "apikey_id": {
                "type": "string",
                "readOnly": true,
                "description": "Unique identifier for the API key (external ID, system-generated)",
                "example": "a1b2c3d4e5f6"
              },
              "organization_id": {
                "type": "string",
                "readOnly": true,
                "description": "Organization ID that owns this API key (system-managed)",
                "example": "org_xxxxxxxxxx"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "readOnly": true,
                "description": "Creation timestamp (system-managed, UTC timezone)"
              },
              "secret_masked": {
                "type": "string",
                "description": "Masked secret key (for display purposes)",
                "example": "sk_live_abc***xyz"
              },
              "is_suspended": {
                "type": "boolean",
                "description": "Whether the API key is suspended due to billing or policy reasons.\nSuspended API keys cannot be used but remain visible in the system.\nThis is different from deletion - suspended keys can be reactivated.\n"
              },
              "suspension_reason": {
                "type": "string",
                "nullable": true,
                "description": "Reason why the API key is suspended (e.g. billing, policy_violation).\nThis field is only set when the API key is suspended for billing or policy reasons,\nnot when it is deleted by the user.\n"
              }
            }
          }
        ]
      },
      "APIKeyList": {
        "allOf": [
          {
            "$ref": "#/components/schemas/APIKeyInDB"
          },
          {
            "type": "object",
            "properties": {
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Expiration time based on created_at and ttl.\nReturns null if ttl is null (key never expires).\n"
              }
            }
          }
        ]
      },
      "APIKeyListResponse": {
        "type": "object",
        "required": [
          "apikeys",
          "pagination"
        ],
        "properties": {
          "apikeys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIKeyList"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "APIKeyCreate": {
        "allOf": [
          {
            "$ref": "#/components/schemas/APIKeyInDB"
          },
          {
            "type": "object",
            "required": [
              "secret_key"
            ],
            "properties": {
              "secret_key": {
                "type": "string",
                "description": "Secret key for the API key. Only returned on creation.\nThis is the only time the full secret key will be available.\nPrefix: `sk_live_` for production.\n",
                "example": "sk_live_2ecWxzqNVMT4AMD7xFEfWSWC6fio9h..."
              }
            }
          }
        ]
      },
      "BillingAddress": {
        "type": "object",
        "required": [
          "line1"
        ],
        "properties": {
          "line1": {
            "type": "string",
            "description": "The first line of the street address, such as street name, house number, building name, etc.\n",
            "example": "1-2-3 Shibuya"
          },
          "line2": {
            "type": "string",
            "nullable": true,
            "description": "The second line of the address, optional, such as apartment number, suite number, floor, etc.\n",
            "example": "Apt 502"
          },
          "city": {
            "type": "string",
            "description": "City/Region (City). Required in some countries and depends on the region.\n",
            "example": "Shibuya-ku"
          },
          "state": {
            "type": "string",
            "description": "State/Province. May be required depending on the country.\n",
            "example": "Tokyo"
          },
          "postal_code": {
            "type": "string",
            "description": "Zip / Postal Code.\n",
            "example": "1500002"
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO 3166-1 alpha-2 two-digit country code, for example: 'JP', 'US'.\n",
            "example": "JP"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Phone number.",
            "example": "+810123456789"
          },
          "email": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$",
            "description": "Email address.",
            "example": "jane@example.com"
          },
          "addressee_name": {
            "type": "string",
            "nullable": true,
            "description": "Addressee name - the name that appears on invoices.\n",
            "example": "Stayforge LLC"
          }
        }
      },
      "UserInfo": {
        "type": "object",
        "required": [
          "sub"
        ],
        "properties": {
          "sub": {
            "type": "string",
            "description": "User identifier (subject) from Auth0",
            "example": "google-oauth2|117899346661318779991"
          },
          "given_name": {
            "type": "string",
            "description": "User's given name (first name)",
            "example": "Junpei"
          },
          "family_name": {
            "type": "string",
            "description": "User's family name (last name)",
            "example": "Ikuta"
          },
          "nickname": {
            "type": "string",
            "description": "User's nickname",
            "example": "junpei"
          },
          "name": {
            "type": "string",
            "description": "User's full name",
            "example": "Junpei Ikuta"
          },
          "picture": {
            "type": "string",
            "format": "uri",
            "description": "URL to user's profile picture",
            "example": "https://lh3.googleusercontent.com/a/ACg8ocJ4JC_WK8rNA9wcGoLvCxuPMEmZCSae2kc08O17YZAP2vSB0g=s96-c"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time of user information",
            "example": "2025-12-31T04:50:26.416Z"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User's email address",
            "example": "junpei@stayforge.co"
          },
          "email_verified": {
            "type": "boolean",
            "description": "Whether the email address has been verified",
            "example": true
          }
        }
      },
      "TenantEnvironmentEnum": {
        "type": "string",
        "enum": [
          "development",
          "staging",
          "production"
        ],
        "description": "Available environment types for tenants",
        "default": "development"
      },
      "TenantMembership": {
        "type": "object",
        "required": [
          "tenant_id",
          "member_sub",
          "role"
        ],
        "properties": {
          "tenant_id": {
            "type": "string",
            "readOnly": true,
            "description": "Tenant ID.",
            "example": "ten_xxxxxxxxxx"
          },
          "member_sub": {
            "type": "string",
            "description": "Member sub from auth0",
            "example": "auth0|xxxxxxxxxxxxxxx"
          },
          "role": {
            "$ref": "#/components/schemas/MemberRoleEnum",
            "description": "Role of the member.",
            "example": "admin"
          },
          "profile": {
            "$ref": "#/components/schemas/UserInfo",
            "nullable": true,
            "description": "Profile of the member. Only included when explicitly requested."
          }
        }
      },
      "TenantDeviceMetrics": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of devices",
            "example": 150
          },
          "online": {
            "type": "integer",
            "nullable": true,
            "description": "Number of online devices.\n**Note:** This field may be null if the logging system is not yet implemented.\n",
            "example": 120
          },
          "unlocks_today": {
            "type": "integer",
            "nullable": true,
            "description": "Number of unlocks in the last 24 hours (from now).\n**Note:** This field may be null if the logging system is not yet implemented.\n",
            "example": 450
          }
        }
      },
      "TenantCardMetrics": {
        "type": "object",
        "properties": {
          "active": {
            "type": "integer",
            "description": "Number of active cards",
            "example": 500
          },
          "inactive": {
            "type": "integer",
            "description": "Number of inactive cards",
            "example": 50
          },
          "total": {
            "type": "integer",
            "description": "Total number of cards",
            "example": 550
          }
        }
      },
      "TenantRealtimeMetrics": {
        "type": "object",
        "properties": {
          "devices": {
            "$ref": "#/components/schemas/TenantDeviceMetrics",
            "description": "Device-related metrics"
          },
          "cards": {
            "$ref": "#/components/schemas/TenantCardMetrics",
            "description": "Card-related metrics"
          }
        }
      },
      "TenantYesterdaySnapshot": {
        "type": "object",
        "properties": {
          "devices": {
            "$ref": "#/components/schemas/TenantDeviceMetrics",
            "nullable": true,
            "description": "Device metrics snapshot at yesterday UTC 00:00.\n**Note:** This field may be null if the logging system is not yet implemented.\n"
          },
          "cards": {
            "$ref": "#/components/schemas/TenantCardMetrics",
            "nullable": true,
            "description": "Card metrics snapshot at yesterday UTC 00:00.\n**Note:** This field may be null if the logging system is not yet implemented.\n"
          }
        }
      },
      "TenantMetrics": {
        "type": "object",
        "properties": {
          "realtime": {
            "$ref": "#/components/schemas/TenantRealtimeMetrics",
            "description": "Real-time metrics. These metrics are cached for 15 minutes to improve performance.\n"
          },
          "yesterday": {
            "$ref": "#/components/schemas/TenantYesterdaySnapshot",
            "nullable": true,
            "description": "Metrics snapshot from yesterday UTC 00:00.\n**Note:** This field may be null if the logging system is not yet implemented.\n"
          }
        }
      },
      "MyResources": {
        "type": "object",
        "required": [
          "organizations",
          "tenants"
        ],
        "properties": {
          "organizations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganizationDetail"
            },
            "description": "List of organizations the current user belongs to"
          },
          "tenants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TenantDetail"
            },
            "description": "List of tenants the current user belongs to"
          }
        }
      },
      "TenantInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 4,
            "maxLength": 64,
            "description": "Name of the tenant.",
            "example": "Lobbyist Hotel"
          },
          "description": {
            "type": "string",
            "maxLength": 1024,
            "nullable": true,
            "description": "Description of the tenant",
            "example": "Could heart back forward can food support."
          },
          "environment": {
            "$ref": "#/components/schemas/TenantEnvironmentEnum",
            "description": "Environments of the tenant",
            "default": "development",
            "example": "development"
          }
        }
      },
      "TenantUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 4,
            "maxLength": 64,
            "description": "Name of the tenant.",
            "example": "Lobbyist Hotel"
          },
          "description": {
            "type": "string",
            "maxLength": 1024,
            "nullable": true,
            "description": "Description of the tenant",
            "example": "Could heart back forward can food support."
          },
          "environment": {
            "$ref": "#/components/schemas/TenantEnvironmentEnum",
            "description": "Environments of the tenant",
            "default": "development",
            "example": "development"
          },
          "parent_organization": {
            "type": "string",
            "nullable": true,
            "description": "Parent organization ID",
            "example": "org_69136e52ae56a37415f19365"
          }
        }
      },
      "TenantMembershipCreate": {
        "type": "object",
        "required": [
          "member_sub",
          "role"
        ],
        "properties": {
          "member_sub": {
            "type": "string",
            "description": "Member sub from auth0",
            "example": "auth0|xxxxxxxxxxxxxxx"
          },
          "role": {
            "$ref": "#/components/schemas/MemberRoleEnum",
            "description": "Role of the member.",
            "example": "admin"
          }
        },
        "description": "Request model for creating tenant membership"
      },
      "TenantMembershipUpdate": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "$ref": "#/components/schemas/MemberRoleEnum",
            "description": "New role of the member.",
            "example": "admin"
          }
        },
        "description": "Request model for updating tenant membership"
      }
    },
    "parameters": {
      "ApiKeyHeader": {
        "name": "X-API-Key",
        "in": "header",
        "required": true,
        "description": "API Key for authentication. Get your API key from [dash.stayforge.io/settings/apikeys](https://dash.stayforge.io/settings/apikeys). \nAPI keys must be prefixed with `sk_live_`.\n",
        "schema": {
          "type": "string",
          "example": "sk_live_example_key_1234567890"
        }
      },
      "AuthorizationHeader": {
        "name": "Authorization",
        "in": "header",
        "required": true,
        "description": "User's Access Token for authentication. \nInclude the token in the Authorization header as: `Authorization: Bearer <token>`\nThis authentication method is used for API Key management endpoints.\nUsers must have admin or owner role in the organization to manage API keys.\n",
        "schema": {
          "type": "string",
          "pattern": "^Bearer .+",
          "example": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
        }
      },
      "OrganizationIdPath": {
        "name": "organization_id",
        "in": "path",
        "required": true,
        "description": "Organization identifier",
        "schema": {
          "type": "string",
          "pattern": "^org_[a-zA-Z0-9_-]+$",
          "example": "org_4e7a2daebd497c2c"
        }
      },
      "CardNumberPath": {
        "name": "card_number",
        "in": "path",
        "required": true,
        "description": "Card number identifier",
        "schema": {
          "$ref": "#/components/schemas/CardNumberSchema"
        }
      },
      "TenantIdPath": {
        "name": "tenant_id",
        "in": "path",
        "required": true,
        "description": "Tenant identifier",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[a-zA-Z0-9_-]+$",
          "example": "ten_1234567890"
        }
      },
      "MemberSubPath": {
        "name": "member_sub",
        "in": "path",
        "required": true,
        "description": "Member sub from auth0",
        "schema": {
          "type": "string",
          "minLength": 1,
          "pattern": "^[a-zA-Z0-9|_-]+$",
          "example": "auth0|xxxxxxxxxxxxxxx"
        }
      },
      "DeviceIdPath": {
        "name": "device_id",
        "in": "path",
        "required": true,
        "description": "Device identifier",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
          "example": "device-001"
        }
      },
      "APIKeyIdPath": {
        "name": "apikey_id",
        "in": "path",
        "required": true,
        "description": "API Key identifier",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[a-zA-Z0-9_-]+$",
          "example": "a1b2c3d4e5f6"
        }
      },
      "InviteIdPath": {
        "name": "invite_id",
        "in": "path",
        "required": true,
        "description": "Invitation identifier",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^inv_[a-zA-Z0-9]+$",
          "example": "inv_abc123xyz"
        }
      },
      "InviteStatusQuery": {
        "name": "status",
        "in": "query",
        "required": false,
        "description": "Filter by status: `active`, `expired`, `exhausted`, `revoked`, `all` (default: `active`)\n- active: is_active=true AND not expired AND not exhausted\n- expired: is_active=true AND expires_at <= now\n- exhausted: is_active=true AND max_uses > 0 AND current_uses >= max_uses\n- revoked: is_active=false\n- all: Return all invites regardless of status\n",
        "schema": {
          "type": "string",
          "enum": [
            "active",
            "expired",
            "exhausted",
            "revoked",
            "all"
          ],
          "default": "active",
          "example": "active"
        }
      },
      "PageQuery": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "Page number (starts from 1).\nIf not provided, defaults to 1.\nDefault: 1, Maximum: 1000000\n",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 1000000,
          "default": 1,
          "example": 1
        }
      },
      "LimitQuery": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Number of items per page (1-100).\nIf not provided, defaults to 20.\nDefault: 20, Maximum: 100\n",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20,
          "example": 20
        }
      },
      "CardNumberQuery": {
        "name": "number",
        "in": "query",
        "required": false,
        "description": "Card No. (must be unique within your organization).\nIf not provided, a unique card number will be automatically generated.\nProvide this only when you must set a specific card number; otherwise omit it to let the system generate one.\n",
        "schema": {
          "$ref": "#/components/schemas/CardNumberSchema"
        }
      },
      "ModelPath": {
        "name": "model",
        "in": "path",
        "required": true,
        "description": "Device model name (e.g., VG-M350)",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
          "minLength": 1,
          "maxLength": 64,
          "example": "VG-M350"
        }
      }
    }
  }
}