Skip to content

Slice 001 - API Schema & Data Model (Draft)

Date: 2026-02-06

Scope

Integrations catalog and Connections CRUD/Test APIs that satisfy Slice 001 acceptance criteria.

Assumptions

  • Tenant-isolated data planes with tenant/workspace scope enforcement.
  • A Connection is owned by exactly one workspace and cannot be executed across workspaces.
  • API-first: UI consumes only these APIs.

RBAC (v0)

Roles: - Admin - Connector Builder - Viewer/Auditor

Rules: - Viewer/Auditor: read-only, cannot create/edit/delete or see secrets. - Admin, Connector Builder: full access to create/edit/delete; can test connection.

API Surface (v0)

Base: /v1

Integrations

GET /integrations - Auth: any role - Semantics: returns the global connector catalog available in the tenant deployment. - Response: 

{
  "integrations": [
    {
      "integration_id": "aws",
      "name": "Amazon Web Services",
      "connector_type": "discovery",
      "provider_system": "aws",
      "connector_id": "aws-discovery",
      "version": "0.1.0",
      "required_permissions": ["..."],
      "emits_entities": ["Principal", "Account", "Entitlement", "Resource", "CloudAccountBoundary"],
      "emits_relationships": ["principal_represents_account", "account_assigned_entitlement", "entitlement_grants_resource"],
      "limits_blind_spots": ["..."],
      "supports_test": true
    }
  ]
}

Connections

GET /connections - Auth: any role - Query: integration_id (optional) - Response: 

{
  "connections": [
    {
      "connection_id": "conn_123",
      "integration_id": "aws",
      "connector_id": "aws-discovery",
      "connector_version": "0.1.0",
      "name": "Prod AWS",
      "tenant_id": "t_123",
      "workspace_id": "w_123",
      "scope": {
        "aws_accounts": ["123456789012"]
      },
      "schedule": {
        "type": "daily",
        "hour": 2,
        "minute": 0
      },
      "status": "healthy",
      "last_run_at": "2026-02-06T10:12:00Z"
    }
  ]
}

POST /connections - Auth: Admin, Connector Builder - Request: 

{
  "integration_id": "aws",
  "name": "Prod AWS",
  "scope": {"aws_accounts": ["123456789012"]},
  "schedule": {"type": "daily", "hour": 2, "minute": 0},
  "configuration": {
    "access_key_id": "...",
    "secret_access_key": "...",
    "region": "us-east-1"
  }
}
- Response: 201 with Connection (secrets omitted)

GET /connections/{connection_id} - Auth: any role - Response: Connection (secrets omitted)

PATCH /connections/{connection_id} - Auth: Admin, Connector Builder - Request: partial fields; configuration optional - Response: Connection (secrets omitted)

DELETE /connections/{connection_id} - Auth: Admin, Connector Builder - Response: 204

POST /connections/{connection_id}/test - Auth: Admin, Connector Builder - Response: 

{
  "status": "success|failure",
  "checked_at": "2026-02-06T10:12:00Z",
  "remediation": [
    {"category": "permissions", "message": "Missing iam:ListUsers", "action": "Add the permission to the role"}
  ]
}

Data Model (Draft)

Table: integrations

  • integration_id (pk) (e.g., aws, azure, cyberark_identity)
  • name
  • connector_id
  • connector_version
  • connector_type (discovery)
  • provider_system (aws|azure|cyberark_identity)
  • required_permissions (jsonb)
  • emits_entities (jsonb)
  • emits_relationships (jsonb)
  • limits_blind_spots (jsonb)
  • supports_test (bool)
  • created_at, updated_at

Table: connections

  • connection_id (pk)
  • tenant_id (indexed)
  • workspace_id (indexed)
  • integration_id (fk)
  • connector_id
  • connector_version
  • name
  • configuration_ciphertext (bytea/jsonb)
  • configuration_kms_key_id (text)
  • configuration_schema_version (text)
  • scope (jsonb)
  • schedule (jsonb)
  • status (healthy|degraded|unknown)
  • last_run_at (timestamp)
  • created_at, updated_at

Table: connection_tests

  • test_id (pk)
  • connection_id (indexed)
  • tenant_id, workspace_id
  • status (success|failure)
  • checked_at
  • remediation (jsonb)
  • created_at

Table: audit_events

  • event_id (pk)
  • tenant_id, workspace_id
  • actor_id
  • action (connection_created|connection_edited|connection_deleted|connection_tested)
  • target_type (connection)
  • target_id
  • payload (jsonb)
  • created_at

Notes

  • Secret values are never returned by API.
  • configuration_ciphertext stored using AWS KMS envelope encryption.
  • workspace_id scopes all queries; cross-workspace access is forbidden even within the same tenant.
  • Connector catalog visibility may be filtered by permission/licensing entitlements.
  • Cross-tenant API behavior is out of scope for v0 product flows.