Projects

Projects are the second level of resource scoping in CRAFT. Every resource (agents, data connections, artifacts, files) belongs to a project, and every project belongs to an organization. Projects provide:

Logical separation of resources within a single organization
Permission inheritance from the parent organization via OpenFGA
Access control through project-level roles (owner, admin, developer, operator, viewer)

The project_id is never embedded in the JWT token. It is supplied via the X-Project-ID request header, allowing users to switch project context without re-authenticating.

How Projects Work

When a project is created, the platform performs several coordinated actions:

Database Record

A project record is created in the Governance database, linked to the parent organization by organization_id.

OpenFGA Parent Link

A relationship tuple is written to OpenFGA linking the project to its organization: project:{project_id}#organization@organization:{org_id}. This establishes permission inheritance — organization-level roles automatically grant access to the project.

Default Group Permissions

Default project groups receive appropriate permissions:

project-owners -> owner relation
project-admins -> admin relation
project-developers -> developer relation
project-operators -> operator relation
project-viewers -> viewer relation

The X-Project-ID Header

All resource APIs (Assets, Utils) require the X-Project-ID header to scope requests:

# List data connections in a specific project
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Project-ID: my-analytics-project" \
     https://api.example.com/assets/data

This design choice has important implications:

Why not put project_id in the JWT?

Users often work across multiple projects in the same session. Embedding project_id in the JWT would require re-authentication to switch projects. The header-based approach allows instant project switching with the same token.

How is the header validated?

The require_permission() dependency reads the X-Project-ID header and checks OpenFGA to verify the authenticated user has the required permission on that project. If the user lacks access, a 403 is returned.

What about list operations?

List queries always filter by both auth.org_id (from JWT) and project_id (from header). This dual filter ensures data isolation even if a permission check has a gap.

API Reference

The Projects API is part of the Governance service (port 8000).

GET /governance/projects

Lists all projects in the user’s organization with pagination. Results are filtered to only include projects the user has can_read permission on.Query Parameters:

page (default: 1) — Page number
limit (default: 20, max: 100) — Items per page

Response (200 OK)

{
  "data": [
    {
      "id": "analytics-prod",
      "name": "Analytics Production",
      "description": "Production analytics project",
      "organization_id": "acme-corp",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

POST /governance/projects

Creates a new project within the user’s organization (determined from JWT). The project is automatically linked to the organization and default groups receive permissions.Access: Users with can_manage_projects on the organization (owners or admins).

Request Body

{
  "name": "Analytics Production",
  "description": "Production analytics project",
  "external_id": "analytics-prod",
  "create_users": false
}

If external_id is omitted, a UUID is generated for the project ID.

Response (201 Created)

{
  "id": "analytics-prod",
  "external_id": "analytics-prod",
  "name": "Analytics Production",
  "organization_id": "acme-corp",
  "created_at": "2026-04-01T12:00:00Z"
}

GET /governance/projects/{project_id}

Retrieves detailed information about a specific project.Access: Users with can_read permission on the project.

Response (200 OK)

{
  "name": "Analytics Production",
  "description": "Production analytics project",
  "organization_id": "acme-corp",
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-02T08:30:00Z"
}

Project Permissions

Projects define a richer role set than organizations, supporting fine-grained access control for resource management:

Permission	Owner	Admin	Developer	Operator	Viewer
`can_read`	Yes	Yes	Yes	Yes	Yes
`can_write`	Yes	Yes	Yes	Yes	—
`can_delete`	Yes	Yes	—	—	—
`can_create_resources`	Yes	Yes	Yes	—	—
`can_read_secrets`	Yes	Yes	Yes	Yes	—
`can_manage_secrets`	Yes	Yes	Yes	—	—
`can_read_metadata`	Yes	Yes	Yes	Yes	—
`can_manage_metadata`	Yes	Yes	Yes	—	—

Project permissions also inherit from the parent organization. An organization owner or admin automatically has can_read, can_write, can_delete, and can_create_resources on all projects in their organization, even without explicit project-level role assignment.

Service Accounts

Projects support service relations for background workers and automated processes:

Service Relation	Grants
`service_reader`	`can_read`, `can_read_secrets`, `can_read_metadata`
`service_writer`	`can_read`, `can_write`, `can_read_secrets`, `can_manage_secrets`, `can_read_metadata`, `can_manage_metadata`
`service_deleter`	`can_read`, `can_delete`
`service_executor`	`can_execute` (for MCP servers, API servers, data connections)

Service accounts authenticate via the master realm with a svc- client ID prefix and are granted contextual tuples scoped to specific projects. See Service Accounts for setup instructions and token management.

Overview

Identity & Access

Agents & Services

Memory

Data & Gateways

Projects

Projects

How Projects Work

The X-Project-ID Header

API Reference

Project Permissions

Service Accounts

Next Steps

Organizations

Authorization

Data Connections

Agent Registry

​Projects

​How Projects Work

​The X-Project-ID Header

​API Reference

​Project Permissions

​Service Accounts

​Next Steps

Organizations

Authorization

Data Connections

Agent Registry

Projects

How Projects Work

The X-Project-ID Header

API Reference

Project Permissions

Service Accounts

Next Steps