Projects

Logical resource groupings within organizations, providing project-level scoping, permission inheritance, and the X-Project-ID header convention.

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:

1. Database Record

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

2. 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.

3. 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 8001).

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.

Next Steps

Organizations

Understand how organizations provide the top-level tenant boundary.

Authorization

Explore the OpenFGA permission model and permission inheritance.

Data Connections

Manage database and storage connections within projects.

Agent Registry

Register and discover agents scoped to projects.