diff --git a/content/docs/ktrlplane/api/authentication.mdx b/content/docs/ktrlplane/api/authentication.mdx deleted file mode 100644 index e4b6def..0000000 --- a/content/docs/ktrlplane/api/authentication.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Authentication API -description: How to authenticate with KtrlPlane APIs using Auth0 JWT tokens and scopes ---- -# Authentication API - -The Authentication API describes how clients obtain and use JWT tokens to interact securely with KtrlPlane. - -KtrlPlane relies on Auth0 for identity management. All API requests require a valid bearer token and proper scopes. - -## Overview - -Clients authenticate using Auth0's OAuth2/OIDC flows. The resulting access token must include the audience configured for KtrlPlane and appropriate scopes for platform access. - -## Required Headers - -Include the following header in every authenticated request: - -```http -Authorization: Bearer -``` - -## Token Acquisition - -Typical SPA / browser clients use Auth0's Authorization Code Flow with PKCE. Server-side scripts may use Client Credentials (if allowed) for backend automation. - -### Authorization Code Flow (PKCE) -1. Redirect user to Auth0 authorization endpoint -2. User logs in / consents -3. Auth0 redirects back with authorization code -4. Exchange code + PKCE verifier for tokens - -### Client Credentials Flow (Optional) -Used for machine-to-machine communication. Tokens issued will reflect configured app-level permissions. - -## Scopes - -KtrlPlane defines the following high-level scope for platform access: - -- `access:platform` – Grants access to core control plane APIs (projects, resources, RBAC, billing) - -Additional fine-grained permission checks are enforced via RBAC at the project, resource, and organization levels. - -## Token Validation - -Tokens are validated by middleware that: -- Verifies signature against Auth0 JSON Web Keys (JWKS) -- Checks token expiration -- Confirms audience matches configured API audience -- Extracts user identity (sub, email) for context - -## Error Responses - -| Status | Description | -|--------|-------------| -| 401 Unauthorized | Missing or invalid token | -| 403 Forbidden | Authenticated but lacks required RBAC permission | - -## Example Request - -```bash -curl -H "Authorization: Bearer $JWT_TOKEN" \ - https://ktrlplane.konnektr.io/api/v1/projects -``` - -## Next Steps - -- [Projects API](/api/projects) – Manage user workspaces -- [RBAC API](/api/rbac) – Understand access control -- [Resources API](/api/resources) – Deploy platform resources diff --git a/content/docs/ktrlplane/api/billing.mdx b/content/docs/ktrlplane/api/billing.mdx deleted file mode 100644 index d135be2..0000000 --- a/content/docs/ktrlplane/api/billing.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Billing API -description: Billing and subscription management endpoints for organizations and projects ---- -# Billing API - -Billing endpoints manage Stripe customer creation, subscriptions, and portal sessions at both organization and project scopes. - -## Overview -Billing can be configured at either the organization or project level. Projects may inherit billing from their parent organization. - -## Organization Billing Endpoints -```http -GET /api/v1/organizations/{orgId}/billing -PUT /api/v1/organizations/{orgId}/billing -POST /api/v1/organizations/{orgId}/billing/customer -POST /api/v1/organizations/{orgId}/billing/subscription -POST /api/v1/organizations/{orgId}/billing/portal -POST /api/v1/organizations/{orgId}/billing/cancel -GET /api/v1/organizations/{orgId}/billing/status -POST /api/v1/organizations/{orgId}/billing/setup-intent -``` - -## Project Billing Endpoints -```http -GET /api/v1/projects/{projectId}/billing -PUT /api/v1/projects/{projectId}/billing -POST /api/v1/projects/{projectId}/billing/customer -POST /api/v1/projects/{projectId}/billing/subscription -POST /api/v1/projects/{projectId}/billing/portal -POST /api/v1/projects/{projectId}/billing/cancel -GET /api/v1/projects/{projectId}/billing/status -POST /api/v1/projects/{projectId}/billing/setup-intent -``` -## Billing Status Endpoint - -Returns billing status, payment method status, and Stripe subscription info for onboarding/payment enforcement. - -```http -GET /api/v1/organizations/{orgId}/billing/status** -GET /api/v1/projects/{projectId}/billing/status** -``` - -**Response:** - -## Billing API Overview - -KtrlPlane uses Stripe for all billing and payment processing. Billing information is managed centrally and inherited by projects and resources as needed. All billing info is sourced directly from Stripe; the database does **not** store SubscriptionStatus, SubscriptionPlan, or BillingEmail fields. - -### Key Concepts - -- **Billing Account**: Each organization or project can have a billing account, managed via Stripe. The `billing_accounts` table is the canonical source for Stripe IDs (customer, subscription, etc.). Projects and organizations reference billing_accounts only; Stripe IDs are not stored in their tables. -- **Subscription**: Subscriptions are managed via Stripe and linked to billing accounts. Subscription status and cancellation are reflected live from Stripe. -- **Invoices**: The UI displays the **last invoice** (not upcoming) from Stripe. The "Current Period" field has been removed for clarity. - -### API Endpoints - -- `GET /api/v1/billing/account` - Retrieve billing account details -- `POST /api/v1/billing/account` - Create or update billing account -- `GET /api/v1/billing/invoices` - List invoices for the billing account -- `GET /api/v1/billing/subscription` - Get subscription details -- `POST /api/v1/billing/subscription/cancel` - Cancel subscription at period end - -### UI/UX Behavior - -- Stripe is the single source of truth for billing info. -- The UI shows the last invoice, not upcoming. -- If a subscription is pending cancellation (`cancel_at_period_end` is true), the UI displays a clear warning and disables the cancel button, guiding users to the Payment Management Portal to continue their subscription. -- All billing and subscription actions are managed via Stripe and surfaced in the UI. - -### Cancellation Workflow - -- To cancel a subscription, users schedule cancellation at the end of the current billing period. -- If cancellation is already scheduled, the UI shows a warning and provides a link to the Payment Management Portal to continue the subscription if desired. - -### Security & Compliance - -- All billing endpoints require JWT authentication and RBAC enforcement. -- No sensitive payment data is stored in the KtrlPlane database. - -### Example Response - -```json -{ - "billing_account": { - "id": "acct_123", - "stripe_customer_id": "cus_abc", - "stripe_subscription_id": "sub_xyz" - }, - "subscription_details": { - "id": "sub_xyz", - "status": "active", - "cancel_at_period_end": true, - "current_period_end": 1704067200 - }, - "latest_invoice": { - "id": "in_456", - "amount_due": 1000, - "currency": "usd", - "period_start": 1701388800, - "period_end": 1704067200, - "status": "paid", - "hosted_invoice_url": "https://..." - } -} -``` -- [Resources API](/api/resources) diff --git a/content/docs/ktrlplane/api/meta.json b/content/docs/ktrlplane/api/meta.json deleted file mode 100644 index 8784a63..0000000 --- a/content/docs/ktrlplane/api/meta.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "title": "API Reference", - "pages": [ - "authentication", - "organizations", - "projects", - "resources", - "rbac", - "billing", - "observability" - ] -} \ No newline at end of file diff --git a/content/docs/ktrlplane/api/observability.mdx b/content/docs/ktrlplane/api/observability.mdx deleted file mode 100644 index f40d157..0000000 --- a/content/docs/ktrlplane/api/observability.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Observability API" -description: "Secure, multi-tenant proxy endpoints for logs and metrics in KtrlPlane." ---- -# Observability API - -KtrlPlane provides secure, multi-tenant proxy endpoints for accessing logs and metrics data from your resources. - -## Overview - -The observability endpoints allow you to query logs and metrics for resources within your projects. All requests are authenticated, authorized through RBAC, and automatically scoped to the correct organization tenant. - -## Authentication - -All observability endpoints require: -- Valid Auth0 JWT token in the `Authorization` header -- `read` permission on the project containing the resource - -## Endpoints - -### Logs - -```http -GET /api/v1/projects/{projectId}/resources/{resourceId}/logs -``` - -Proxies log queries to Loki with automatic tenant scoping and resource filtering. - -**Parameters:** -- `query` (string): LogQL query expression -- `start` (string): Start time (RFC3339 format or Unix timestamp) -- `end` (string): End time (RFC3339 format or Unix timestamp) -- `limit` (integer): Maximum number of log lines to return (default: 1000) - -**Example:** -```bash -curl -H "Authorization: Bearer $JWT_TOKEN" \ - "https://ktrlplane.konnektr.io/api/v1/projects/my-project/resources/my-resource/logs?query={level=\"error\"}&start=2025-01-27T10:00:00Z&end=2025-01-27T11:00:00Z&limit=100" -``` - -### Metrics - -```http -GET /api/v1/projects/{projectId}/resources/{resourceId}/metrics/query_range -``` - -Proxies metrics queries to Mimir with automatic tenant scoping and resource filtering. - -**Parameters:** -- `query` (string): PromQL query expression -- `start` (string): Start time (RFC3339 format or Unix timestamp) -- `end` (string): End time (RFC3339 format or Unix timestamp) -- `step` (string): Query step duration (e.g., "15s", "1m", "5m") - -**Example:** -```bash -curl -H "Authorization: Bearer $JWT_TOKEN" \ - "https://ktrlplane.konnektr.io/api/v1/projects/my-project/resources/my-resource/metrics/query_range?query=cpu_usage_percent&start=2025-01-27T10:00:00Z&end=2025-01-27T11:00:00Z&step=15s" -``` - -## Security & Multi-Tenancy - -### RBAC Enforcement -- Users must have `read` permission on the project containing the resource -- Resource access is validated for each request -- Unauthorized requests return `403 Forbidden` - -### Automatic Tenant Scoping -- All requests include the `X-Scope-OrgID` header for multi-tenancy -- Tenant ID is set to the project ID for project-level isolation -- Prevents cross-project data access - -### Query Filtering -- **Logs**: LogQL queries are automatically prefixed with `{resource_id="resourceId"}` -- **Metrics**: PromQL queries are automatically filtered with `{resource_id="resourceId"}` -- Ensures users only see data from the requested resource - -## Configuration - -Enable observability backends in your `config.yaml`: - -```yaml -observability: - loki: - enabled: true - url: "http://loki-gateway:3100" - mimir: - enabled: true - url: "http://mimir-gateway:8080" -``` - -## Environment Variables - -- `KTRLPLANE_OBSERVABILITY_LOKI_ENABLED`: Enable Loki logging backend -- `KTRLPLANE_OBSERVABILITY_LOKI_URL`: Loki server URL -- `KTRLPLANE_OBSERVABILITY_MIMIR_ENABLED`: Enable Mimir metrics backend -- `KTRLPLANE_OBSERVABILITY_MIMIR_URL`: Mimir server URL - -## Error Responses - -- `401 Unauthorized`: Missing or invalid authentication token -- `403 Forbidden`: Insufficient permissions to access resource -- `404 Not Found`: Resource not found -- `502 Bad Gateway`: Backend observability service unavailable -- `503 Service Unavailable`: Observability backend not configured - -## Backend Integration - -The proxy forwards requests to: -- **Loki**: `/loki/api/v1/query_range` endpoint -- **Mimir**: `/prometheus/api/v1/query_range` endpoint - -Both backends must support multi-tenancy via the `X-Scope-OrgID` header (set to project ID). \ No newline at end of file diff --git a/content/docs/ktrlplane/api/organizations.mdx b/content/docs/ktrlplane/api/organizations.mdx deleted file mode 100644 index ad69876..0000000 --- a/content/docs/ktrlplane/api/organizations.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Organizations API -description: Manage organizations, their settings, billing, and access control within KtrlPlane ---- -# Organizations API - -Organizations are top-level containers grouping projects, users, and billing contexts. - -Base URL: -```text -https://ktrlplane.konnektr.io/api/v1 -``` - -All endpoints require a valid bearer token and appropriate RBAC permissions. - -## Organization Object - -```typescript -interface Organization { - organization_id: string; - name: string; - created_at: string; // ISO 8601 - updated_at: string; // ISO 8601 - billing_inherited?: boolean; - stripe_customer_id?: string; -} -``` - -## List Organizations -```http -GET /api/v1/organizations -``` -Returns organizations the current user can access. - -### Example -```bash -curl -H "Authorization: Bearer $JWT_TOKEN" \ - https://ktrlplane.konnektr.io/api/v1/organizations -``` - -## Create Organization -```http -POST /api/v1/organizations -``` -### Request Body -```json -{ - "id": "org-abc123", - "name": "Acme Corp" -} -``` - -## Get Organization -```http -GET /api/v1/organizations/{orgId} -``` - -## Update Organization -```http -PUT /api/v1/organizations/{orgId} -``` -### Request Body -```json -{ - "name": "Acme Corporation" -} -``` - -## Delete Organization -```http -DELETE /api/v1/organizations/{orgId} -``` -Irreversible. Projects under the organization must be handled prior to deletion. - -## RBAC: Role Assignments -```http -GET /api/v1/organizations/{orgId}/rbac -POST /api/v1/organizations/{orgId}/rbac -DELETE /api/v1/organizations/{orgId}/rbac/{assignmentId} -``` -Manages organization-level roles (e.g., org_owner, org_admin, org_viewer). - -## Billing -```http -GET /api/v1/organizations/{orgId}/billing -PUT /api/v1/organizations/{orgId}/billing -POST /api/v1/organizations/{orgId}/billing/customer -POST /api/v1/organizations/{orgId}/billing/subscription -POST /api/v1/organizations/{orgId}/billing/portal -POST /api/v1/organizations/{orgId}/billing/cancel -``` -Controls billing settings and Stripe integration. - -## Error Responses -| Status | Description | -|--------|-------------| -| 400 Bad Request | Invalid input | -| 401 Unauthorized | Missing/invalid token | -| 403 Forbidden | Insufficient permission | -| 404 Not Found | Organization does not exist | - -## Next Steps -- [Projects API](/api/projects) -- [RBAC API](/api/rbac) -- [Billing API](/api/billing) diff --git a/content/docs/ktrlplane/api/projects.mdx b/content/docs/ktrlplane/api/projects.mdx deleted file mode 100644 index 9524d3c..0000000 --- a/content/docs/ktrlplane/api/projects.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Projects API -description: Manage projects which group resources, RBAC scope, and billing context ---- -# Projects API - -Projects are workspaces under an organization that contain resources and define an RBAC boundary. - -Base URL: -```text -https://ktrlplane.konnektr.io/api/v1 -``` - -## Project Object -```typescript -interface Project { - project_id: string; - organization_id: string; - name: string; - created_at: string; // ISO 8601 - updated_at: string; // ISO 8601 - billing_inherited?: boolean; -} -``` - -## List Projects -```http -GET /api/v1/projects -``` -Returns projects the user can access. - -## Create Project -```http -POST /api/v1/projects -``` -### Request Body -```json -{ - "id": "proj-abc123", - "organization_id": "org-abc123", - "name": "Customer Analytics" -} -``` - -## Get Project -```http -GET /api/v1/projects/{projectId} -``` - -## Update Project -```http -PUT /api/v1/projects/{projectId} -``` -### Request Body -```json -{ - "name": "Customer Intelligence" -} -``` - -## Delete Project -```http -DELETE /api/v1/projects/{projectId} -``` -Requires elevated permission (e.g., project_owner). - -## RBAC: Role Assignments -```http -GET /api/v1/projects/{projectId}/rbac -POST /api/v1/projects/{projectId}/rbac -DELETE /api/v1/projects/{projectId}/rbac/{assignmentId} -``` - -## Billing -```http -GET /api/v1/projects/{projectId}/billing -PUT /api/v1/projects/{projectId}/billing -POST /api/v1/projects/{projectId}/billing/customer -POST /api/v1/projects/{projectId}/billing/subscription -POST /api/v1/projects/{projectId}/billing/portal -POST /api/v1/projects/{projectId}/billing/cancel -``` -Supports project-level billing configuration or inheritance from organization. - -## Nested Resources -See [Resources API](/api/resources) for managing deployable units within a project. - -## Error Responses -| Status | Description | -|--------|-------------| -| 400 Bad Request | Invalid input | -| 401 Unauthorized | Missing/invalid token | -| 403 Forbidden | Insufficient permission | -| 404 Not Found | Project does not exist | - -## Next Steps -- [Resources API](/api/resources) -- [RBAC API](/api/rbac) -- [Billing API](/api/billing) diff --git a/content/docs/ktrlplane/api/rbac.mdx b/content/docs/ktrlplane/api/rbac.mdx deleted file mode 100644 index 8fe4bf3..0000000 --- a/content/docs/ktrlplane/api/rbac.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: RBAC API -description: Role-based access control endpoints for assigning and validating permissions ---- -# RBAC API - -RBAC (Role-Based Access Control) governs access at organization, project, and resource scopes. - -## Overview - -Roles map to a collection of permissions. Users receive roles via assignments scoped to a specific organization, project, or resource. - -## Global Roles Listing -```http -GET /api/v1/roles -``` -Returns all system-defined roles. - -## Permissions Check -```http -GET /api/v1/permissions/check?scopeType=project&scopeId=proj-abc123 -GET /api/v1/permissions/check?scopeType=project&scopeId=proj-abc123&userId=auth0|123 -``` - -Returns actions the current user (or specified user) can perform within the specified scope. - -**Query Parameters:** -- `scopeType` (required): `"organization"`, `"project"`, or `"resource"` -- `scopeId` (required): The ID of the specific scope -- `userId` (optional): Check permissions for a specific user (requires service account with `check_permissions_on_behalf_of` permission) - -**Response:** -```json -{ - "user_id": "auth0|123456789", - "scope_type": "project", - "scope_id": "my-project-id", - "permissions": ["read", "write", "manage_access"] -} -``` - -**Note:** Regular users can only check their own permissions. Service accounts (M2M) with the special permission can check any user's permissions. See [Service Accounts Guide](/guides/service-accounts) for details. - -## Role Assignments - -### Organization Level -```http -GET /api/v1/organizations/{orgId}/rbac -POST /api/v1/organizations/{orgId}/rbac -DELETE /api/v1/organizations/{orgId}/rbac/{assignmentId} -``` - -### Project Level -```http -GET /api/v1/projects/{projectId}/rbac -POST /api/v1/projects/{projectId}/rbac -DELETE /api/v1/projects/{projectId}/rbac/{assignmentId} -``` - -### Resource Level -```http -GET /api/v1/projects/{projectId}/resources/{resourceId}/rbac -POST /api/v1/projects/{projectId}/resources/{resourceId}/rbac -DELETE /api/v1/projects/{projectId}/resources/{resourceId}/rbac/{assignmentId} -``` - -## Role Assignment Object -```typescript -interface RoleAssignment { - assignment_id: string; - user_id: string; - role: string; // e.g. project_viewer, project_editor, project_owner - scope_type: "organization" | "project" | "resource"; - scope_id: string; - created_at: string; -} -``` - -## Common Roles (Examples) -| Role | Description | -|------|-------------| -| org_owner | Full organization control | -| project_owner | Manage project + billing | -| project_editor | Create/update resources | -| project_viewer | Read-only project access | -| resource_editor | Modify resource configuration | -| resource_viewer | Read-only resource access | - -## Error Responses -| Status | Description | -|--------|-------------| -| 400 Bad Request | Invalid role or scope | -| 401 Unauthorized | Missing/invalid token | -| 403 Forbidden | Insufficient permission | -| 404 Not Found | Scope does not exist | - -## Next Steps -- [Projects API](/api/projects) -- [Resources API](/api/resources) -- [Authentication API](/api/authentication) diff --git a/content/docs/ktrlplane/api/resources.mdx b/content/docs/ktrlplane/api/resources.mdx deleted file mode 100644 index 83e0efe..0000000 --- a/content/docs/ktrlplane/api/resources.mdx +++ /dev/null @@ -1,377 +0,0 @@ ---- -title: Resources API -description: Complete API reference for managing resources in KtrlPlane ---- - -# Resources API - -The Resources API allows you to create, manage, and configure resources within your projects. Resources represent deployable services like Graph databases, Flow processors, and AI Assemblers. - -## Base URL - -``` -https://ktrlplane.konnektr.io/api/v1 -``` - -## Authentication - -All API requests require authentication using JWT tokens. Include the token in the Authorization header: - -```http -Authorization: Bearer -``` - -## Resource Object - -```typescript -interface Resource { - resource_id: string; - project_id: string; - name: string; - type: string; // "Konnektr.Graph" | "Konnektr.Flow" | "Konnektr.Assembler" | "Konnektr.Compass" - sku: string; // "free" | "pro" | "enterprise" - status: string; // "creating" | "running" | "updating" | "error" | "terminated" - settings_json: object; // Resource-specific configuration - created_at: string; // ISO 8601 timestamp - updated_at: string; // ISO 8601 timestamp - error_message?: string; // Present when status is "error" - access_url?: string; // Service endpoint URL -} -``` - -## List Resources - -Retrieve all resources in a project. - -```http -GET /projects/{projectId}/resources -``` - -### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `projectId` | string | Yes | Project identifier | - -### Example Request - -```bash -curl -X GET \ - "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources" \ - -H "Authorization: Bearer $JWT_TOKEN" -``` - -### Example Response - -```json -{ - "resources": [ - { - "resource_id": "res-graph-xyz789", - "project_id": "proj-abc123", - "name": "Production Graph DB", - "type": "Konnektr.Graph", - "sku": "pro", - "status": "running", - "settings_json": { - "database_name": "production-twins", - "enable_analytics": true, - "backup_retention_days": 30 - }, - "created_at": "2025-01-15T10:30:00Z", - "updated_at": "2025-01-15T10:35:00Z", - "access_url": "https://graph-xyz789.konnektr.io/api/v1" - } - ], - "total": 1, - "limit": 50, - "offset": 0 -} -``` - -## Create Resource - -Create a new resource in a project. - -```http -POST /projects/{projectId}/resources -``` - -### Request Body - -```typescript -interface CreateResourceRequest { - id: string; // Unique resource identifier - name: string; // Display name - type: string; // Resource type - sku?: string; // Billing tier (default: "free") - settings_json?: object; // Resource configuration -} -``` - -### Example Request - -```bash -curl -X POST \ - "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources" \ - -H "Authorization: Bearer $JWT_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "id": "my-graph-db", - "name": "Customer Analytics Graph", - "type": "Konnektr.Graph", - "sku": "pro", - "settings_json": { - "database_name": "customer-analytics", - "enable_analytics": true, - "backup_retention_days": 30, - "max_concurrent_connections": 100 - } - }' -``` - -### Example Response - -```json -{ - "resource_id": "res-graph-abc456", - "project_id": "proj-abc123", - "name": "Customer Analytics Graph", - "type": "Konnektr.Graph", - "sku": "pro", - "status": "creating", - "settings_json": { - "database_name": "customer-analytics", - "enable_analytics": true, - "backup_retention_days": 30, - "max_concurrent_connections": 100 - }, - "created_at": "2025-01-15T14:20:00Z", - "updated_at": "2025-01-15T14:20:00Z" -} -``` - -## Get Resource - -Retrieve a specific resource by ID. - -```http -GET /projects/{projectId}/resources/{resourceId} -``` - -### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `projectId` | string | Yes | Project identifier | -| `resourceId` | string | Yes | Resource identifier | - -### Example Request - -```bash -curl -X GET \ - "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources/res-graph-xyz789" \ - -H "Authorization: Bearer $JWT_TOKEN" -``` - -### Example Response - -```json -{ - "resource_id": "res-graph-xyz789", - "project_id": "proj-abc123", - "name": "Production Graph DB", - "type": "Konnektr.Graph", - "sku": "pro", - "status": "running", - "settings_json": { - "database_name": "production-twins", - "enable_analytics": true, - "backup_retention_days": 30, - "max_concurrent_connections": 200, - "enable_audit_logging": true - }, - "created_at": "2025-01-15T10:30:00Z", - "updated_at": "2025-01-15T12:45:00Z", - "access_url": "https://graph-xyz789.konnektr.io/api/v1" -} -``` - -## Update Resource - -Update an existing resource's configuration. - -```http -PUT /projects/{projectId}/resources/{resourceId} -``` - -### Request Body - -```typescript -interface UpdateResourceRequest { - name?: string; // Update display name - sku?: string; // Change billing tier - settings_json?: object; // Update configuration -} -``` - -### Example Request - -```bash -curl -X PUT \ - "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources/res-graph-xyz789" \ - -H "Authorization: Bearer $JWT_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Updated Graph Database", - "settings_json": { - "database_name": "production-twins", - "enable_analytics": true, - "backup_retention_days": 60, - "max_concurrent_connections": 300, - "enable_audit_logging": true - } - }' -``` - -### Example Response - -```json -{ - "resource_id": "res-graph-xyz789", - "project_id": "proj-abc123", - "name": "Updated Graph Database", - "type": "Konnektr.Graph", - "sku": "pro", - "status": "updating", - "settings_json": { - "database_name": "production-twins", - "enable_analytics": true, - "backup_retention_days": 60, - "max_concurrent_connections": 300, - "enable_audit_logging": true - }, - "created_at": "2025-01-15T10:30:00Z", - "updated_at": "2025-01-15T15:20:00Z" -} -``` - -## Delete Resource - -Delete a resource permanently. - -```http -DELETE /projects/{projectId}/resources/{resourceId} -``` - - -This action is irreversible. All data associated with the resource will be permanently deleted. - - -### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `projectId` | string | Yes | Project identifier | -| `resourceId` | string | Yes | Resource identifier | - -### Example Request - -```bash -curl -X DELETE \ - "https://ktrlplane.konnektr.io/api/v1/projects/proj-abc123/resources/res-graph-xyz789" \ - -H "Authorization: Bearer $JWT_TOKEN" -``` - -### Example Response - -```json -{ - "message": "Resource deletion initiated", - "resource_id": "res-graph-xyz789", - "status": "deleting" -} -``` - -## Resource Configuration Schemas - -### Resource Configuration - -Each resource type accepts a flexible `settings_json` object. The specific schema depends on the resource type and is validated by the respective Konnektr product. - -**Example Graph Settings:** -```json -{ - "database_name": "my-graph-db", - "enable_analytics": true, - "backup_retention_days": 30 -} -``` - -**Example Flow Settings:** -```json -{ - "max_concurrent_flows": 10, - "retention_days": 7, - "processing_mode": "streaming" -} -``` - -**Example Assembler Settings:** -```json -{ - "model_complexity": "standard", - "output_format": "dtdl_v2", - "confidence_threshold": 0.8 -} -``` - - -Settings are stored as flexible JSON and passed to the respective Konnektr product for validation and processing. Refer to each product's documentation for supported configuration options. - - -## Resource Status Codes - -| Status | Description | -|--------|-------------| -| `creating` | Resource is being provisioned | -| `running` | Resource is operational and available | -| `error` | Resource encountered an error (check error_message) | -| `deleting` | Resource is being deleted | - -## Error Handling - -### Common Error Responses - -#### 400 Bad Request -```json -{ - "error": "Failed to create resource", - "details": "Invalid resource configuration" -} -``` - -#### 403 Forbidden -```json -{ - "error": "Insufficient permissions to create resource" -} -``` - -#### 404 Not Found -```json -{ - "error": "Resource not found" -} -``` - -## SDK Support - -KtrlPlane SDKs are planned for future releases. Currently, you can interact with the API directly using HTTP clients in your preferred programming language. - -## Next Steps - -- **[Authentication API](/api/authentication)**: Learn about API authentication -- **[Projects API](/api/projects)**: Manage projects that contain resources -- **[RBAC API](/api/rbac)**: Control access to resources -- **[Billing API](/api/billing)**: Monitor resource costs and usage \ No newline at end of file diff --git a/content/docs/ktrlplane/concepts/access-control.mdx b/content/docs/ktrlplane/concepts/access-control.mdx index 9553ab5..c448987 100644 --- a/content/docs/ktrlplane/concepts/access-control.mdx +++ b/content/docs/ktrlplane/concepts/access-control.mdx @@ -2,52 +2,69 @@ title: Access Control description: Learn how role-based access control (RBAC) governs permissions across organizations, projects, and resources --- + # Access Control -KtrlPlane uses Role-Based Access Control (RBAC) to manage permissions at three hierarchical scopes: organization, project, and resource. - -## Core Principles -- **Scoped Roles**: Roles are always assigned within a scope (org, project, resource) -- **Least Privilege**: Users should receive only the permissions necessary -- **Composability**: Access can layer—organization visibility and project edit rights, for example -- **Auditability**: Role assignments form the backbone of audit trails - -## Scopes -| Scope | Example | Role Examples | Description | -|-------|---------|---------------|-------------| -| Organization | `org-abc123` | org_owner, org_admin, org_viewer | Top-level grouping boundary | -| Project | `proj-xyz123` | project_owner, project_editor, project_viewer | Application/workspace boundary | -| Resource | `res-graph-01` | resource_editor, resource_viewer | Individual deployable unit | - -## Roles (Conceptual) -| Role | Typical Permissions | -|------|---------------------| -| org_owner | Manage organization + billing + projects | -| org_admin | Manage organization configuration | -| org_viewer | Read-only organization visibility | -| project_owner | Full project control including billing override | -| project_editor | Create/update resources | -| project_viewer | Read-only project and resources | -| resource_editor | Change resource configuration | -| resource_viewer | View resource status, metrics, logs | - -## Permission Evaluation -1. Authenticate user (JWT token) -2. Identify scope from request path -3. Load role assignments for user + scope -4. Resolve permissions and compare against required action - -## Best Practices -- Periodically audit high-privilege roles -- Use resource-level roles only when finer granularity is required -- Prefer project-level roles for most collaboration scenarios - -## Common Scenarios -- A user needs to view logs: must have resource_viewer or project_viewer (with access) + logs feature enabled -- A user needs to change resource settings: resource_editor or project_editor -- A user needs to delete a project: project_owner - -## Next Steps -- [RBAC API](/api/rbac) -- [Projects](/concepts/projects) -- [Resources](/concepts/resources) +KtrlPlane uses a robust Role-Based Access Control (RBAC) system to ensure that users have exactly the permissions they need—no more, no less. Permissions are managed hierarchically across three scopes: **Organization**, **Project**, and **Resource**. + +## Permission Scopes + +Access can be granted at three different levels. Permissions granted at a higher level automatically inherit down to lower levels. + +| Scope | Description | Example | +|-------|-------------|---------| +| **Organization** | The top-level boundary. Roles assigned here apply to the entire organization and all projects within it. | granting `Owner` on the Organization gives full control over all projects. | +| **Project** | A workspace for related resources. Roles assigned here apply to all resources within the project. | Granting `Viewer` on a Project allows a user to see all resources in that project. | +| **Resource** | The individual deployable unit (e.g., a specific Graph or Secret). Roles assigned here apply ONLY to that specific resource. | Granting `Editor` on a specific Secret allows modifying that secret but nothing else. | + +## System Roles + +KtrlPlane provides a set of pre-defined roles designed to cover common access patterns. These roles are categorized into **Platform Access**, **Data Access**, and **Resource-Specific Access**. + +### Platform Access Roles +These roles control access to the KtrlPlane control plane (configuration, deployment, settings). + +| Role | Permissions | Best For | +|------|-------------|----------| +| **Owner** | Full administrative access. Can manage billing, users, roles, and delete the scope (Project/Org). | Organization Admins, Project Leads | +| **Editor** | Can create, update, and delete resources. Cannot manage user access or billing. | Developers, DevOps Engineers | +| **Viewer** | Read-only access to configuration and status. Cannot make any changes. | Auditors, Support Staff, Stakeholders | + +### Data Access Roles +These roles control access to the *data plane*—the actual data stored within your resources. + +| Role | Description | +|------|-------------| +| **Konnektr.Data.Owner** | Grants full access to the data within resources. For example, allows querying all nodes in a Graph or reading values in a Secret. | + + + **Control Plane vs. Data Plane**: An `Editor` can change the configuration of a database (Control Plane) but might not have permission to read the customer data inside it (Data Plane). Assign `Konnektr.Data.Owner` to grant data access. + + +### Resource-Specific Roles +These roles are tailored for specific resource types and offer more granular control. + +* **Konnektr.Graph.Owner**, **Konnektr.Graph.Editor**, **Konnektr.Graph.Viewer** +* **Konnektr.Flow.Owner**, **Konnektr.Flow.Editor**, **Konnektr.Flow.Viewer** +* **Konnektr.Secret.Owner**, **Konnektr.Secret.Editor**, **Konnektr.Secret.Viewer** + +Use these when you need to grant access to a specific *type* of resource without granting blanket access to the entire project. + +## Inheritance Model + +Permissions are additive and hierarchical. +* **Organization Owner** implies **Project Owner** for all projects. +* **Project Viewer** implies **Resource Viewer** for all resources in that project. + +Best Practice: Assign roles at the **Project** level for teams to reduce management overhead. Use **Resource** level assignments only for exceptions (e.g., a specific secret that only one person should see). + +## Managing Access + +To manage access: +1. Navigate to the scope you want to manage (Organization Settings, Project Settings, or Resource Details). +2. Click on the **"Access"** or **"Permissions"** tab. +3. Click **"Add Assignment"**. +4. Select the **User** (by email) and the **Role**. +5. Save the assignment. + +Effective permissions are calculated instantly, allowing users immediate access. diff --git a/content/docs/ktrlplane/guides/creating-resources.mdx b/content/docs/ktrlplane/guides/creating-resources.mdx new file mode 100644 index 0000000..e5291f7 --- /dev/null +++ b/content/docs/ktrlplane/guides/creating-resources.mdx @@ -0,0 +1,60 @@ +--- +title: Creating Resources +description: Step-by-step guide to creating and configuring new resources in KtrlPlane +--- + +# Creating Resources + +This guide walks you through the process of creating new resources in your KtrlPlane projects. KtrlPlane uses a unified wizard to make resource creation simple and consistent across different types. + +## The Creation Wizard + +To start creating a resource: +1. Navigate to your **Project** dashboard. +2. Click the **"Add Resource"** button in the top right or the **"Create Resource"** card in the dashboard. + +### Step 1: Select Resource Type + +Choose the type of resource you need from the catalog. + +* **Konnektr.Graph**: A high-performance graph database for digital twins. +* **Konnektr.Flow**: A real-time event processing and routing engine. +* **Konnektr.Assembler**: An AI-powered tool for generating data models. + +### Step 2: Configure Details + +1. **Name**: Enter a unique display name for your resource. +2. **ID**: A DNS-compliant ID will be automatically generated from your name. You can customize this if needed, but it must be unique within the project. +3. **Tier**: Select a performance tier. + * **Free**: Good for development and testing. Shared infrastructure. + * **Pro**: For production workloads requiring guaranteed performance. + * **Enterprise**: Dedicated infrastructure with custom SLAs. + +### Step 3: Billing (If Required) + +If you select a paid tier (Pro or Enterprise) and haven't set up billing for your project yet, you will be prompted to: +1. Enter your billing details. +2. Add a payment method via the secure Stripe portal. + +*Note: You only need to do this once per project.* + +### Step 4: Resource Configuration + +Different resources require different configuration settings. + +* **Graphs**: configuring database names, backup retention, and scaling options. +* **Flows**: configuring processing modes (streaming/batch), retention policies, and instance counts. +* **Secrets**: Add key-value pairs for sensitive data. + +Refer to the specific product documentation for detailed configuration parameters for each resource type. + +### Step 5: Creation and Deployment + +Once configured, click **Create Resource**. KtrlPlane will provision your dedicated infrastructure. This process typically takes 1-3 minutes. You will be redirected to the resource details page automatically. + +## Next Steps + +After your resource is created: +1. **View Details**: Check the resource overview for status and connection endpoints. +2. **Manage Access**: Use the **Access** tab to grant permissions to other users or service accounts. +3. **Check Logs**: Use the **Logs** tab to monitor initialization and runtime events. diff --git a/content/docs/ktrlplane/guides/meta.json b/content/docs/ktrlplane/guides/meta.json index 3c94b2d..be36336 100644 --- a/content/docs/ktrlplane/guides/meta.json +++ b/content/docs/ktrlplane/guides/meta.json @@ -1,6 +1,7 @@ { "title": "User Guides", "pages": [ + "creating-resources", "resources", "service-accounts" ] diff --git a/content/docs/ktrlplane/guides/resources.mdx b/content/docs/ktrlplane/guides/resources.mdx index 8959e51..c925729 100644 --- a/content/docs/ktrlplane/guides/resources.mdx +++ b/content/docs/ktrlplane/guides/resources.mdx @@ -9,120 +9,28 @@ This comprehensive guide covers everything you need to know about managing resou ## Creating Resources -### Step 1: Resource Planning - -Before creating a resource, consider: - -**Purpose and Requirements** -- What functionality do you need? -- What are your performance requirements? -- Do you need real-time processing or batch operations? -- What are your data storage requirements? - -**Integration Needs** -- Will this resource integrate with other resources in your project? -- Do you need external API connections? -- Are there specific data formats or protocols required? - -**Scale and Growth** -- What's your expected initial usage? -- How might usage grow over time? -- Do you need auto-scaling capabilities? - -### Step 2: Resource Selection - -Choose the appropriate resource type: - -#### Konnektr.Graph -**Choose when you need:** -- Connected data storage and querying -- Relationship mapping and analysis -- Digital twin data models -- Complex data relationships - -#### Konnektr.Flow -**Choose when you need:** -- Real-time event processing -- Data transformation and routing -- Workflow automation -- Stream processing - -#### Konnektr.Assembler -**Choose when you need:** -- AI-powered model generation -- Automated data mapping -- DTDL model creation -- Intelligent schema inference - -### Step 3: Tier Selection - -Select the appropriate tier based on your needs: - -| Feature | Free | Pro | Enterprise | -|---------|------|-----|------------| -| **Cost** | $0/month | Custom pricing | Custom pricing | -| **Use Case** | Development & testing | Production workloads | Enterprise scale | -| **Support** | Community | Email support | Dedicated support | -| **Features** | Full functionality | Full functionality + SLA | Custom features + SLA | - - -All tiers currently provide full functionality for development and testing. Tier-specific limits and billing enforcement are planned features. - +For a detailed step-by-step walkthrough of the creation process, please refer to the **[Creating Resources](/guides/creating-resources)** guide. -### Step 4: Configuration +## Secret Management -Configure your resource settings based on your requirements: +KtrlPlane employs a modern, secure approach to secret management that minimizes the need for handling long-lived static credentials. -#### Graph Configuration Example -```json -{ - "database_name": "production-twins", - "enable_analytics": true, - "backup_retention_days": 30, - "query_timeout_seconds": 60, - "max_concurrent_connections": 200, - "enable_audit_logging": true, - "performance_tier": "standard", - "auto_scaling": { - "enabled": true, - "min_capacity": 2, - "max_capacity": 10 - } -} -``` +### Federated Identity +For integrations with external services like Kafka or Azure Data Explorer, KtrlPlane utilizes **Federated Identity** (Workload Identity). This means you don't need to manually create or store secrets for these connections. Instead, you configure the connection details (like endpoints or cluster URIs), and authentication is handled securely and automatically via OAUTHBEARER tokens. -#### Flow Configuration Example -```json -{ - "max_concurrent_flows": 25, - "retention_days": 90, - "enable_dead_letter_queue": true, - "processing_mode": "streaming", - "error_handling": "retry_with_backoff", - "auto_scaling": { - "enabled": true, - "min_instances": 2, - "max_instances": 20, - "target_cpu_utilization": 70 - } -} -``` +### Project Credentials (M2M) +For programmatic access to the KtrlPlane API (e.g., for CI/CD pipelines or external scripts), you should use **Service Accounts**. -#### Assembler Configuration Example -```json -{ - "model_complexity": "standard", - "output_format": "dtdl_v2", - "confidence_threshold": 0.8 -} -``` +1. Navigate to your **Project Dashboard**. +2. Locate the **API Authentication** card. +3. You will see your **Client ID** and **Client Secret**. +4. Use these credentials to obtain an access token via the standard OAuth2 Client Credentials flow. -### Step 5: Deployment + + Store your Client Secret securely. It is only visible to Project Admins and allows full programmatic access to your project's resources. + -1. Review your configuration -2. Click **"Create Resource"** -3. Monitor the deployment progress -4. Wait for the resource to become available (typically 2-5 minutes) +For more details on using these credentials, see the [Service Accounts](/guides/service-accounts) guide. ## Managing Existing Resources diff --git a/content/docs/ktrlplane/introduction.mdx b/content/docs/ktrlplane/introduction.mdx index 0a50ba6..29dc3c7 100644 --- a/content/docs/ktrlplane/introduction.mdx +++ b/content/docs/ktrlplane/introduction.mdx @@ -1,6 +1,5 @@ --- -title: "KtrlPlane" -root: true +title: "KtrlPlane Documentation" description: "Centralized management for users, organizations, projects, resources, billing, and RBAC in the Konnektr Platform." ---