Projects

The Projects module provides multi-tenant namespaces in SOAT. Every resource (document, file, actor, conversation) belongs to a project. Projects are identified by an id prefixed with proj_.

Overview

A Project is a top-level container that scopes all resources. Users access projects through policy-based authorization — there is no separate membership table. Whether a user can access a project is determined entirely by the policies attached to their account and the SRN patterns those policies contain.

See the Permissions Reference for the IAM action strings for this module.

Related Tutorials

• Chat with an LLM - Step 2 (Create a project)
• Permissions in Practice - Step 3 (Create the Analytics project)
• Deploy a Multi-Agent App with Agent Formation - Step 2 (Create a project)

Data Model

Field	Type	Description
id	string	Public identifier prefixed with proj_
name	string	Human-readable project name
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last-updated timestamp

Key Concepts

Project Access via Policies

Users no longer need to be explicitly added to a project as members. Access is granted by attaching a Policy to the user (or their API key) that contains an Allow statement covering the relevant project's SRN pattern:

{
  "statement": [
    {
      "effect": "Allow",
      "action": ["projects:GetProject", "files:ListFiles", "files:GetFile"],
      "resource": ["soat:proj_ABC:*:*"]
    }
  ]
}

To grant a user access to all projects, use a wildcard project segment:

{ "resource": ["soat:*:*:*"] }

Visibility Rules

• Admin users see all projects.
• API key callers scoped to a project see only that project.
• Regular users see only the projects covered by the SRN patterns in their attached policies.

Authorization Model

Authorization is policy-only — there is no Layer 1 membership gate. All access decisions are evaluated through the policy engine against the requested action and the resource SRN. See IAM for details.

Examples

Create a project

CLI

soat create-project --name "My Project"

SDK

// SDK
import { SoatClient } from '@soat/sdk';
const soat = new SoatClient({
  baseUrl: 'https://api.example.com',
  token: 'sk_...',
});

const { data, error } = await soat.projects.createProject({
  body: { name: 'My Project' },
});
if (error) throw new Error(JSON.stringify(error));

curl

curl -X POST https://api.example.com/api/v1/projects \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project"}'

Get a project

CLI

soat get-project --project-id proj_ABC

SDK

// SDK
const { data, error } = await soat.projects.getProject({
  path: { project_id: 'proj_ABC' },
});
if (error) throw new Error(JSON.stringify(error));

curl

curl https://api.example.com/api/v1/projects/proj_ABC \
  -H "Authorization: Bearer <token>"