Skip to main content

​
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:
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.
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.
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).
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
  }
}
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"
}
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:
PermissionOwnerAdminDeveloperOperatorViewer
can_readYesYesYesYesYes
can_writeYesYesYesYes—
can_deleteYesYes———
can_create_resourcesYesYesYes——
can_read_secretsYesYesYesYes—
can_manage_secretsYesYesYes——
can_read_metadataYesYesYesYes—
can_manage_metadataYesYesYes——
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 RelationGrants
service_readercan_read, can_read_secrets, can_read_metadata
service_writercan_read, can_write, can_read_secrets, can_manage_secrets, can_read_metadata, can_manage_metadata
service_deletercan_read, can_delete
service_executorcan_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.