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

Organizations

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

Projects

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)

Agents

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:

Protocol	Description	Discovery
A2A (Agent-to-Agent)	Open protocol for inter-agent communication using JSON-RPC 2.0 over SSE	Agent Cards at `/.well-known/agent-card.json`
MCP (Model Context Protocol)	Protocol for providing context to LLMs through tool definitions and resource access	MCP server metadata with tool/resource/prompt indexing
agentskills.io	Portable skill format for packaging agent capabilities	Skill packages linked to Agent Card registrations

Agents are registered in the Assets service (port 8002) and can be searched across all three protocols with a single query.Agent lifecycle stages: EXPERIMENTAL, STABLE, DEPRECATED, RETIREDRelated: Agent Registry | Data Insights Agents

Data Connections

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 8002)
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

Schedules

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 8003).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 (Coming Soon)

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

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

Role	Description
`owner`	Full control over the organization and all its resources
`admin`	Administrative access to manage users, projects, and settings
`member`	Standard access to project resources
`developer`	Access to create and modify agents, data connections, and workflows
`operator`	Access to deploy, schedule, and monitor resources
`viewer`	Read-only access to all resources

Computed Permissions

Permissions are derived from role relationships at query time:

Permission	Description
`can_read`	View a resource and its metadata
`can_write`	Create or update a resource
`can_delete`	Remove a resource
`can_execute`	Run an agent, trigger a schedule, or execute a workflow
`can_manage_secrets`	Access and manage secrets for data connections

Inheritance

Permissions flow downward through the hierarchy:

Organization -> Project -> Resource (Agent, Data Connection, etc.)

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.

Module	Status	Purpose
CRAFT Assess	Available	Evaluates data and surfaces what blocks agent-readiness. Implemented today by the Data Insights and Data Governance solutions (data profiling, coverage analysis, policy compliance checks).
CRAFT Enrich	Available	Automatically enriches metadata, generates data quality rules, and classifies data assets. Implemented today by the Data Governance solution (LLM-powered metadata enrichment, DQ rule generation, classification).
CRAFT Toolkit	Planned	Verification certificates and auto-formalization tools for developers extending the platform. Custom data connectors are not part of Toolkit; they are added on-demand to the platform’s data-connections capability.

See Introduction for the user-facing framing.

Glossary of Key Terms

Term	Definition
A2A	Agent-to-Agent. Open protocol for inter-agent communication (JSON-RPC 2.0 over SSE).
Agent Card	A JSON manifest at `/.well-known/agent-card.json` describing an A2A agent’s capabilities and skills
MCP	Model Context Protocol — a protocol for providing context to LLMs through tool definitions
ReBAC	Relationship-Based Access Control — fine-grained authorization based on entity relationships
OIDC	OpenID Connect — the identity layer used by Keycloak for authentication
PKCE	Proof Key for Code Exchange — OAuth 2.0 extension for secure browser-based auth flows
OTel	OpenTelemetry — vendor-neutral observability framework for traces, metrics, and logs
LGTM	Loki, Grafana, Tempo, Mimir — the Grafana observability stack
SSE	Server-Sent Events — unidirectional HTTP streaming used by the A2A protocol

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.

Getting Started

CRAFT Core Concepts

Key Concepts

Core Entities

Permission Model

Roles

Computed Permissions

Inheritance

CRAFT Modules

Glossary of Key Terms

Next Steps

Platform Overview

Authorization

Agent Registry

Security Model

Getting Started

Documentation Index

​Key Concepts

​Core Entities

​Permission Model

​Roles

​Computed Permissions

​Inheritance

​CRAFT Modules

​Glossary of Key Terms

​Next Steps

Platform Overview

Authorization

Agent Registry

Security Model

Key Concepts

Core Entities

Permission Model

Roles

Computed Permissions

Inheritance

CRAFT Modules

Glossary of Key Terms

Next Steps