{ "openapi": "3.0.3", "info": { "title": "Tenant Manager REST API v2", "version": "v2", "description": "Tenant Manager REST API v2 provides tenant and user management capabilities\nusing IAMCore authentication and authorization.\n" }, "servers": [ { "url": "https://cloud.kaaiot.com/tenant-manager/api/v2", "description": "API Server" } ], "paths": { "/keycloak-servers": { "get": { "description": "Retrieve the list of configured Keycloak servers", "responses": { "200": { "description": "Successfully retrieved list of Keycloak servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeycloakServers" } } } } }, "security": [ [ "oauth_2_0" ], [ "api_key" ] ] } }, "/keycloak-servers/{pk}": { "parameters": [ { "name": "pk", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Keycloak server identifier", "example": 0 } ], "get": { "description": "Retrieve details of a specific Keycloak server", "responses": { "200": { "description": "Successfully retrieved Keycloak server details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeycloakServer" } } } }, "404": { "description": "Keycloak server not found" } }, "security": [ [ "oauth_2_0" ], [ "api_key" ] ] } }, "/tenants": { "get": { "description": "Retrieve a paginated list of tenants accessible to the authenticated user", "responses": { "200": { "description": "Successfully retrieved list of tenants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageTenantInfo" }, "example": { "count": 3, "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Production Tenant", "tenant_id": "tenant-prod-001", "status": "AVAILABLE", "opendistro_enabled": true, "subscription_type": "RENEWAL", "package_type": "cloud-5", "admin": { "id": "550e8400-e29b-41d4-a716-446655440001", "irn": "user:admin:123", "email": "admin@example.com", "username": "admin", "first_name": "Admin", "last_name": "Admin" }, "minio": { "key": "minio-key-123", "status": "AVAILABLE" }, "opendistro": { "uuid": "tenant-prod-001", "status": "AVAILABLE" }, "created": "2023-01-01T00:00:00Z", "modified": "2023-01-01T00:00:00Z" }, { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Staging Environment", "tenant_id": "tenant-staging-001", "status": "AVAILABLE", "opendistro_enabled": true, "subscription_type": "TRIAL", "package_type": "cloud-3", "admin": { "id": "550e8400-e29b-41d4-a716-446655440002", "irn": "user:admin:456", "email": "staging-admin@example.com", "username": "staging-admin", "first_name": "Staging", "last_name": "Admin" }, "minio": { "key": "minio-staging-key", "status": "AVAILABLE" }, "opendistro": { "uuid": "tenant-staging-001", "status": "FAILED" }, "created": "2023-01-02T00:00:00Z", "modified": "2023-01-02T00:00:00Z" }, { "id": "550e8400-e29b-41d4-a716-446655440002", "name": "Development Environment", "tenant_id": "tenant-dev-001", "status": "CREATING", "opendistro_enabled": false, "subscription_type": "TRIAL", "package_type": "cloud-1", "minio": { "key": "minio-dev-key", "status": "CREATING" }, "opendistro": { "uuid": "tenant-dev-001", "status": "CREATING" }, "created": "2023-01-03T00:00:00Z", "modified": "2023-01-03T00:00:00Z" } ], "limit": 100, "offset": 0 } } } } }, "security": [ { "oauth_2_0": [ "iamcore:tenant:read" ] }, { "api_key": [ "iamcore:tenant:read" ] } ], "parameters": [ { "name": "tenant_id?", "in": "query", "description": "Filter tenants by tenant ID", "required": false, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "name?", "in": "query", "description": "Filter tenants by name", "required": false, "schema": { "type": "string" }, "example": "my-tenant" }, { "name": "admin?", "in": "query", "description": "Filter tenants by admin username or email", "required": false, "schema": { "type": "string" }, "example": "admin@example.com" } ] }, "post": { "description": "Create a new tenant in the system (asynchronous operation)", "responses": { "202": { "description": "Tenant creation accepted (processing asynchronously)" }, "409": { "description": "Conflict - Tenant with this name already exists" } }, "security": [ { "oauth_2_0": [ "iamcore:tenant:create" ] }, { "api_key": [ "iamcore:tenant:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" }, "example": { "name": "Staging Environment 2", "display_name": "Secondary staging environment", "package_type": "550e8400-e29b-41d4-a716-446655440002", "admin_template_id": "550e8400-e29b-41d4-a716-446655440003", "subscription_end_date": "2024-12-31T23:59:59Z" } } } } } }, "/tenants/{pk}": { "parameters": [ { "name": "pk", "in": "path", "required": true, "schema": { "type": "tenant-manager-api-types.UUID" }, "description": "Unique identifier of the tenant", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "get": { "description": "Retrieve detailed information about a specific tenant", "responses": { "200": { "description": "Successfully retrieved tenant details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" }, "example": { "id": "5428586f-49a1-45b6-9ab7-de56ebd11e03", "name": "Production Tenant", "tenant_id": "tenant-prod-001", "status": "AVAILABLE", "opendistro_enabled": true, "subscription_type": "RENEWAL", "package_type": "cloud-5", "admin": { "id": "550e8400-e29b-41d4-a716-446655440000", "irn": "user:admin:123", "email": "admin@example.com", "username": "admin", "first_name": "Admin", "last_name": "Admin" }, "minio": { "key": "minio-key-123", "status": "AVAILABLE" }, "opendistro": { "uuid": "tenant-prod-001", "status": "AVAILABLE" }, "created": "2023-01-01T00:00:00Z", "modified": "2023-01-01T00:00:00Z" } } } } }, "security": [ { "oauth_2_0": [ "iamcore:tenant:read" ] }, { "api_key": [ "iamcore:tenant:read" ] } ] }, "put": { "description": "Update tenant information", "responses": { "200": { "description": "Tenant updated successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "5428586f-49a1-45b6-9ab7-de56ebd11e03", "name": "Production Tenant", "tenant_id": "tenant-prod-001", "status": "AVAILABLE", "opendistro_enabled": true, "subscription_type": "RENEWAL", "package_type": "cloud-5", "admin": { "id": "550e8400-e29b-41d4-a716-446655440000", "irn": "user:admin:123", "email": "admin@example.com", "username": "admin", "first_name": "Admin", "last_name": "Admin" }, "minio": { "key": "minio-key-123", "status": "AVAILABLE" }, "opendistro": { "uuid": "tenant-prod-001", "status": "AVAILABLE" }, "created": "2023-01-01T00:00:00Z", "modified": "2023-01-01T00:00:00Z" } } } } }, "security": [ { "oauth_2_0": [ "iamcore:tenant:update" ] }, { "api_key": [ "iamcore:tenant:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantRequest" }, "example": { "name": "Staging Environment 2", "display_name": "Secondary staging environment", "package_type": "550e8400-e29b-41d4-a716-446655440002", "admin_template_id": "550e8400-e29b-41d4-a716-446655440003", "subscription_end_date": "2024-12-31T23:59:59Z" } } } } }, "delete": { "description": "Delete a tenant and all associated resources", "responses": { "204": { "description": "Tenant deleted successfully" } }, "security": [ { "oauth_2_0": [ "iamcore:tenant:delete" ] }, { "api_key": [ "iamcore:tenant:delete" ] } ] } }, "/tenants/{pk}/credentials": { "parameters": [ { "name": "pk", "in": "path", "required": true, "schema": { "type": "tenant-manager-api-types.UUID" }, "description": "Unique identifier of the tenant", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "get": { "description": "Retrieve credentials for the specified tenant", "responses": { "200": { "description": "Successfully retrieved tenant credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCredentials" }, "example": { "client_id": "tenant-prod-001-client", "issuer": "https://auth.example.com", "login_url": "https://auth.example.com/login", "minio_secret": "minio-secret-key", "opendistro_secret": "opendistro-secret-key" } } } } }, "security": [ { "oauth_2_0": [ "iamcore:tenant:read" ] }, { "api_key": [ "iamcore:tenant:read" ] } ] } }, "/packages-types": { "get": { "description": "Retrieve available package types", "responses": { "200": { "description": "Successfully retrieved package types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePackageTypeInfo" }, "example": { "count": 7, "results": [ { "id": "00000000-0000-0000-0000-000000000005", "name": "cloud-5", "devices": 5, "applications": 5, "disk_size": 5, "traffic": 5, "description": "Cloud package for 5 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" }, { "id": "00000000-0000-0000-0000-00000000000f", "name": "cloud-15", "devices": 15, "applications": 15, "disk_size": 15, "traffic": 15, "description": "Cloud package for 15 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" }, { "id": "00000000-0000-0000-0000-000000000032", "name": "cloud-50", "devices": 50, "applications": 50, "disk_size": 50, "traffic": 50, "description": "Cloud package for 50 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" }, { "id": "00000000-0000-0000-0000-000000000064", "name": "cloud-100", "devices": 100, "applications": 100, "disk_size": 100, "traffic": 100, "description": "Cloud package for 100 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" }, { "id": "00000000-0000-0000-0000-0000000000fa", "name": "cloud-250", "devices": 250, "applications": 250, "disk_size": 250, "traffic": 250, "description": "Cloud package for 250 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" }, { "id": "00000000-0000-0000-0000-0000000001f4", "name": "cloud-500", "devices": 500, "applications": 500, "disk_size": 500, "traffic": 500, "description": "Cloud package for 500 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" }, { "id": "00000000-0000-0000-0000-0000000003e8", "name": "cloud-1000", "devices": 1000, "applications": 1000, "disk_size": 1000, "traffic": 1000, "description": "Cloud package for 1000 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" } ], "limit": 100, "offset": 0 } } } } }, "security": [ [ "oauth_2_0" ], [ "api_key" ] ] } }, "/packages-types/{pk}": { "parameters": [ { "name": "pk", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package type identifier", "example": "1" } ], "get": { "description": "Retrieve details of a specific package type", "responses": { "200": { "description": "Successfully retrieved package type details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageTypeInfo" }, "example": { "id": "00000000-0000-0000-0000-000000000005", "name": "cloud-5", "devices": 5, "applications": 5, "disk_size": 5, "traffic": 5, "description": "Cloud package for 5 devices", "created": "2023-10-24T18:07:56.709497Z", "modified": "2023-10-24T18:07:56.709497Z" } } } } }, "security": [ [ "oauth_2_0" ], [ "api_key" ] ] } }, "/tenants-subscriptions": { "get": { "description": "Retrieve tenant subscriptions", "responses": { "200": { "description": "Successfully retrieved tenant subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageTenantSubscriptionInfo" }, "example": { "count": 1, "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "tenant_id": "b6d6ac85-e3a2-4153-ad26-5582d2773d40", "package_type": 5, "start_date": "2022-04-21T20:35:36.524970Z", "end_date": "2022-05-21T20:35:36.524970Z" } ], "limit": 100, "offset": 0 } } } } }, "security": [ { "oauth_2_0": [ "kaa:tenant-subscription:read" ] }, { "api_key": [ "kaa:tenant-subscription:read" ] } ], "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter subscriptions by tenant (required)", "required": true, "schema": { "type": "tenant-manager-api-types.UUID" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ] } }, "/users": { "get": { "description": "Retrieve a paginated list of users", "responses": { "200": { "description": "Successfully retrieved list of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageUserTemplateInfo" }, "example": { "count": 1, "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Admin", "last_name": "Admin", "email": "admin@example.com", "username": "admin", "password": "hashed-password", "enabled": true, "users": [ { "id": "user-123", "irn": "user:admin:123", "enabled": true, "tenant_id": "tenant-123" } ], "created": "2023-01-01T00:00:00Z", "modified": "2023-01-01T00:00:00Z" } ], "limit": 100, "offset": 0 } } } } }, "security": [ { "oauth_2_0": [ "kaa:tenant-user:read" ] }, { "api_key": [ "kaa:tenant-user:read" ] } ] }, "post": { "description": "Create a new user in the system", "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTemplateInfo" }, "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Admin", "last_name": "Admin", "email": "admin@example.com", "username": "admin", "password": "hashed-password", "enabled": true, "users": [ { "id": "user-123", "irn": "user:instance:123", "enabled": true, "tenant_id": "tenant-123" } ], "created": "2023-01-01T00:00:00Z", "modified": "2023-01-01T00:00:00Z" } } } } }, "security": [ { "oauth_2_0": [ "kaa:tenant-user:create" ] }, { "api_key": [ "kaa:tenant-user:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserTemplateRequest" }, "example": { "first_name": "Admin", "last_name": "Admin", "email": "admin@example.com", "enabled": true, "username": "admin", "password": "secure-password-123" } } } } } }, "/users/{pk}": { "parameters": [ { "name": "pk", "in": "path", "required": true, "schema": { "type": "tenant-manager-api-types.UUID" }, "description": "Unique identifier of the user", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "delete": { "description": "Delete a user from the system", "responses": { "204": { "description": "User deleted successfully" } }, "security": [ { "oauth_2_0": [ "kaa:tenant-user:delete" ] }, { "api_key": [ "kaa:tenant-user:delete" ] } ] } } }, "components": { "securitySchemes": { "oauth_2_0": { "type": "oauth2", "description": "Tenant Manager v2 supports OAuth 2.0 with IAMCore for authenticating all API requests.\nAll endpoints require valid OAuth 2.0 bearer tokens issued by the IAMCore service.\n", "flows": { "implicit": { "authorizationUrl": "https://auth.example.com/oauth/authorize", "scopes": {} } } }, "api_key": { "type": "oauth2", "description": "Tenant Manager v2 supports long-lived API keys for service-to-service authentication.\nThe API key must be issued by the IAMCore service.\n" } }, "schemas": { "KeycloakServers": { "type": "object", "properties": { "results": { "type": "array", "description": "List of Keycloak servers" } } }, "KeycloakServer": { "type": "object", "properties": { "id": { "type": "integer", "description": "Keycloak server identifier" }, "url": { "type": "string", "description": "URL of the Keycloak server" } } }, "UUID": { "type": "string" }, "TenantStatus": { "type": "string" }, "SubscriptionType": { "type": "string" }, "AdminUserInfo": { "type": "object", "properties": { "id": { "type": "object", "description": "Admin user ID" }, "irn": { "type": "string", "description": "User IRN (Identity Resource Name)" }, "email": { "type": "string", "description": "Admin email address" }, "username": { "type": "string", "description": "Admin username" }, "first_name": { "type": "string", "description": "Admin first name" }, "last_name": { "type": "string", "description": "Admin last name" } } }, "MinioInfo": { "type": "object", "properties": { "key": { "type": "string", "description": "Minio access key" }, "status": { "type": "string", "description": "Minio service status" } } }, "OpendistroInfo": { "type": "object", "properties": { "key": { "type": "string", "description": "Opendistro index key" }, "uuid": { "type": "string", "description": "Opendistro UUID" }, "status": { "type": "string", "description": "Opendistro service status" } } }, "TenantInfo": { "type": "object", "properties": { "id?": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string", "description": "Tenant name" }, "tenant_id": { "type": "string", "description": "Tenant external ID" }, "login_theme?": { "type": "string", "description": "Custom login theme for the tenant" }, "status": { "$ref": "#/components/schemas/TenantStatus" }, "opendistro_enabled": { "type": "boolean", "description": "Whether opendistro is enabled" }, "subscription_type?": { "$ref": "#/components/schemas/SubscriptionType" }, "package_type?": { "type": "string", "description": "Package type identifier" }, "admin?": { "$ref": "#/components/schemas/AdminUserInfo" }, "minio?": { "$ref": "#/components/schemas/MinioInfo" }, "opendistro?": { "$ref": "#/components/schemas/OpendistroInfo" } } }, "PageTenantInfo": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TenantInfo" }, "description": "List of tenant items" } } }, "DateTime": { "type": "string", "format": "date-time" }, "CreateTenantRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Tenant name (required)" }, "display_name?": { "type": "string", "description": "Tenant display name (optional)" }, "package_type": { "type": "object", "description": "Package type ID" }, "admin_template_id": { "type": "object", "description": "Admin user template ID" }, "subscription_type": { "type": "object", "description": "Subscription type (PERMANENT or RENEWAL)" }, "subscription_end_date?": { "$ref": "#/components/schemas/DateTime" } } }, "UpdateTenantRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Tenant name (required)" }, "display_name?": { "type": "string", "description": "Tenant display name (optional)" }, "package_type": { "type": "object", "description": "Package type ID" }, "subscription_type": { "type": "object", "description": "Subscription type" } } }, "TenantCredentials": { "type": "object", "properties": { "client_id": { "type": "string", "description": "OAuth client ID" }, "issuer": { "type": "string", "description": "OAuth issuer URL" }, "login_url": { "type": "string", "description": "Login URL" }, "minio_secret?": { "type": "string", "description": "Minio secret key" }, "opendistro_secret?": { "type": "string", "description": "Opendistro secret key" } } }, "PackageTypeInfo": { "type": "object", "properties": { "id?": { "type": "object", "description": "Package type ID" }, "name": { "type": "string", "description": "Package type name" }, "devices": { "type": "integer", "description": "Number of devices allowed" }, "applications": { "type": "integer", "description": "Number of applications allowed" }, "disk_size": { "type": "integer", "description": "Disk size in MB" }, "traffic": { "type": "integer", "description": "Traffic allowance" }, "description?": { "type": "string", "description": "Package description" } } }, "PagePackageTypeInfo": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PackageTypeInfo" }, "description": "List of package type items" } } }, "TenantSubscriptionInfo": { "type": "object", "properties": { "id?": { "type": "object", "description": "Subscription ID" }, "tenant_id?": { "type": "object", "description": "Tenant ID" }, "package_type": { "type": "object", "description": "Package type identifier" }, "start_date": { "type": "object", "description": "Subscription start date" }, "end_date": { "type": "object", "description": "Subscription end date" } } }, "PageTenantSubscriptionInfo": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TenantSubscriptionInfo" }, "description": "List of subscription items" } } }, "UserInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "irn": { "type": "string", "description": "User IRN" }, "enabled": { "type": "boolean", "description": "Whether user is enabled" }, "tenant_id": { "type": "string", "description": "Tenant ID" } } }, "UserTemplateInfo": { "type": "object", "properties": { "id?": { "type": "object", "description": "User template ID" }, "first_name?": { "type": "string", "description": "First name" }, "last_name?": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Email address" }, "username": { "type": "string", "description": "Username" }, "enabled": { "type": "boolean", "description": "Whether user is enabled" }, "users?": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfo" }, "description": "Associated user instances" } } }, "PageUserTemplateInfo": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserTemplateInfo" }, "description": "List of user template items" } } }, "CreateUserTemplateRequest": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address (must be valid)" }, "first_name": { "type": "string", "description": "First name (required, non-empty)" }, "last_name": { "type": "string", "description": "Last name (required, non-empty)" }, "username": { "type": "string", "description": "Username (required, non-empty)" }, "password": { "type": "string", "description": "Password (min 8 characters)" }, "enabled?": { "type": "boolean", "description": "Whether user should be enabled" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "object", "description": "Additional error details" } } } } } }