Skip to main content

​
Key Concepts

This page introduces the foundational concepts you need to work with CRAFT. Understanding these concepts helps you build and operate any solution on the platform.

​
Core Entities

An organization is the top-level tenant boundary in CRAFT. Every resource in the platform belongs to exactly one organization.Key characteristics:
  • Each organization maps to a single Keycloak realm (the realm ID equals the org ID)
  • Organizations are created during the Governance service bootstrap process
  • All users, projects, and resources are scoped to an organization
  • Cross-organization data access is prevented at the database query level
Identity flow: When you authenticate, your JWT token contains the org_id derived from the Keycloak realm. All subsequent API calls are scoped to that organization automatically.Related: Organizations | Authentication
A project is a logical grouping of resources within an organization. Projects enable teams to organize agents, data connections, and other assets into separate workspaces.Key characteristics:
  • Projects belong to an organization and inherit its permission structure
  • The project_id is passed via the X-Project-ID HTTP header or as a path parameter — it is never stored in the JWT
  • Users can have different roles across different projects within the same organization
  • All list queries filter by both org_id (from JWT) and project_id (from header)
Permission inheritance: Projects inherit permissions from their parent organization via OpenFGA. A user who is an admin of the organization automatically has admin-level computed permissions on all projects within it.Related: Projects | Authorization | Authenticate Users (for solution developers)
An agent is a registered AI service that can be discovered, invoked, and monitored through the platform. CRAFT supports three agent ecosystems through a unified registry:Agents are registered in the Assets service (port 8000) and can be searched across all three protocols with a single query.Agent lifecycle stages: EXPERIMENTAL, STABLE, DEPRECATED, RETIREDRelated: Agent Registry | Data Insights Agents
A data connection is a configured link to an external data source registered in the platform. Solutions use data connections to access customer data without managing credentials directly.Key characteristics:
  • Registered in the Assets service (port 8000)
  • Support databases, APIs, and file stores as data sources
  • Credentials are managed through the platform Secrets API (Infisical or ESO + GCP Secret Manager)
  • Scoped to an organization and project for multi-tenant isolation
  • Used by Data Insights for querying customer databases
  • Used by Data Governance for profiling and enrichment
Security: Data connection credentials are never exposed in API responses. They are stored via the platform Secrets API and injected at runtime only when a solution needs to establish a connection.Related: Data Connections | Data Source Setup Guide
A schedule defines recurring execution of tasks such as data profiling runs, agent health checks, or report generation. Schedules are managed by the Utils service (port 8000).Key characteristics:
  • Cron-based scheduling with timezone support
  • Scoped to an organization and project
  • Integrated with the platform’s permission system (requires can_execute permission)
  • Execution history and status tracking
Related: Schedules
Webhooks are planned for an upcoming release. The webhook system will provide HTTP callbacks to notify external systems when platform events occur. Planned capabilities include HMAC-signed payloads, configurable event filters, automatic retry with exponential backoff, and SSRF protection.Related: Webhooks (Planned)
Multi-tenancy in CRAFT provides complete isolation between organizations while allowing flexible access control within each organization.Isolation model:
  • Authentication isolation: Each organization is a separate Keycloak realm with its own user directory, identity providers, and SSO configuration
  • Authorization isolation: OpenFGA stores per-organization relationship tuples; cross-organization access is structurally impossible
  • Data isolation: Each service owns its own database; all queries filter by org_id from the JWT token
  • Secrets isolation: Secret access is scoped per organization (Infisical namespaces or GCP SM IAM bindings)
Security invariants:
  • The org_id always comes from the authenticated JWT, never from request parameters
  • List operations always filter by org_id AND project_id at the database level
  • Write operations always stamp the org_id from the JWT onto new resources
  • No cross-service foreign keys exist between databases
Related: Multi-Tenancy | Security

​
Permission Model

The platform uses Relationship-Based Access Control (ReBAC) via OpenFGA. Permissions are computed from relationships rather than statically assigned.

​
Roles

​
Computed Permissions

Permissions are derived from role relationships at query time:

​
Inheritance

Permissions flow downward through the hierarchy:
A user with the admin role on an organization automatically receives can_read, can_write, and can_delete computed permissions on all projects and resources within that organization.

​
CRAFT Modules

CRAFT is one product, composed of three modules. Module names are stable nomenclature; capitalize as shown. See Introduction for the user-facing framing.

​
Glossary of Key Terms

​
Next Steps

Platform Overview

Explore the platform services that implement these concepts.

Authorization

Deep dive into OpenFGA and the ReBAC permission model.

Agent Registry

Learn about the unified agent registry across A2A, MCP, and agentskills.io.

Security Model

Understand the full security architecture including authentication, authorization, and secrets.