Project Management

Overview

Projects are sub-resources within an organization that enable logical grouping of resources and users. They provide a way to organize your resources by team, product, environment, or any other logical boundary while maintaining fine-grained access control.

A single organization can contain multiple projects. Each project can have its own set of permissions and access controls.

Project Model

Model
JSON Example

Field	Type	Description
id	uuid	Unique project identifier
name	string	Unique slug for the project. Must contain only alphanumeric characters, dashes, and underscores, and start with a letter. Example: `project-alpha`
title	string	Human-readable display name. Can contain any UTF-8 character. Example: `Project Alpha`
orgId	uuid	Organization ID that the project belongs to
metadata	object	Key-value pairs for additional information. Validated against Project MetaSchema
state	string	Current state: `enabled` or `disabled`
createdAt	timestamp	Creation timestamp
updatedAt	timestamp	Last update timestamp
memberCount	integer	Number of users with access to the project (transient field)

{
  "project": {
    "id": "1b89026b-6713-4327-9d7e-ed03345da288",
    "name": "project-alpha",
    "title": "Project Alpha",
    "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8",
    "metadata": {
      "description": "Production environment for Alpha product",
      "labels": {
        "env": "production",
        "team": "engineering"
      }
    },
    "state": "enabled",
    "createdAt": "2022-12-07T14:31:46.436081Z",
    "updatedAt": "2022-12-07T14:31:46.436081Z"
  }
}

Roles and Permissions

Frontier provides three predefined roles at the project level:

Role	Permissions	Description
app_project_owner	`app_project_administer`	Full control over the project including configuration, access control, and deletion
app_project_manager	`app_project_update` `app_project_get` `app_organization_projectcreate` `app_organization_projectlist`	Can update project details, create new projects, and list projects
app_project_viewer	`app_project_get`	Read-only access to project details and configurations

You can create custom roles with specific permissions at the project level. See Custom Roles below.

Access Control Patterns

Frontier supports two access control patterns for projects:

Project-Level Access

Assign roles at the project level to grant access to all resources within the project. Ideal when users need consistent access across resources.Example: A user with app_project_viewer role can view all resources in the project.

Resource-Level Access

Create policies for individual resources within a project. Provides fine-grained control when different users need different access to specific resources.Example: User A has viewer access to Resource X but manager access to Resource Y, both in the same project.

Creating a Project

Create a new project within an organization.

Identify the Organization

Obtain the organization ID where you want to create the project.

Prepare Project Details

Choose a unique name and prepare metadata.

Create via API

Send a POST request to create the project.

HTTP
CLI
Admin Portal

curl -L -X POST 'https://frontier.example.com/v1beta1/projects' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "name": "project-beta",
    "title": "Project Beta",
    "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8",
    "metadata": {
      "description": "Development environment for Beta features",
      "labels": {
        "env": "development",
        "team": "product"
      }
    }
  }'

frontier project create --file project.yaml

Where project.yaml contains:

name: project-beta
title: Project Beta
orgId: 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8
metadata:
  description: Development environment for Beta features
  labels:
    env: development
    team: product

Authorization Required: User must have app_organization_projectcreate permission in the organization.

Listing Projects

List All Projects (Admin)

Retrieve all projects across all organizations (requires admin access).

curl -L -X GET 'https://frontier.example.com/v1beta1/admin/projects' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

List Organization Projects

Retrieve all projects within a specific organization.

curl -L -X GET 'https://frontier.example.com/v1beta1/organizations/{org_id}/projects' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

# List all projects
frontier project list

# List projects for specific organization
frontier project list --org {org_id}

Getting Project Details

Retrieve detailed information about a specific project.

HTTP
CLI

curl -L -X GET 'https://frontier.example.com/v1beta1/projects/{project_id}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

frontier project view {project_id} --metadata

Authorization Required: User must have app_project_get permission (Owner, Manager, or Viewer role).

Updating a Project

Modify project details such as title or metadata.

HTTP
CLI

curl -L -X PUT 'https://frontier.example.com/v1beta1/projects/{project_id}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "title": "Project Beta - Updated",
    "metadata": {
      "description": "Updated development environment",
      "labels": {
        "env": "staging",
        "team": "product",
        "version": "2.0"
      }
    }
  }'

frontier project edit {project_id} --file updated-project.yaml

Authorization Required: User must have app_project_update permission (Owner or Manager role).

Managing Project Members

Listing Project Users

Retrieve all users who have access to a project (through direct policies or group membership).

curl -L -X GET 'https://frontier.example.com/v1beta1/projects/{project_id}/users' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Listing Project Admins

Retrieve users with administrative access to the project.

curl -L -X GET 'https://frontier.example.com/v1beta1/projects/{project_id}/admins' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Creating Project Policies

Grant users or groups access to a project by creating a policy.

curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/policies' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "roleId": "app_project_viewer",
    "resource": "app/project:{project_id}",
    "principal": "app/user:{user_id}"
  }'

User Access
Group Access
Service Account

# Grant user access to project
curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/policies' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "roleId": "app_project_manager",
    "resource": "app/project:{project_id}",
    "principal": "app/user:2e73f4a2-3763-4dc6-a00e-7a9aebeaa971"
  }'

# Grant group access to project
curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/policies' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "roleId": "app_project_viewer",
    "resource": "app/project:{project_id}",
    "principal": "app/group:86e2f95d-92c7-4c59-8fed-b7686cccbf4f"
  }'

# Grant service account access to project
curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/policies' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "roleId": "app_project_owner",
    "resource": "app/project:{project_id}",
    "principal": "app/serviceuser:f4641672-cfdc-493f-95f0-c440515ad032"
  }'

Authorization Required: User must have app_project_administer permission (Owner role).

Create Custom Roles

Create custom roles with specific permissions at the project level.

curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/roles' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "name": "app_project_deployer",
    "title": "Project Deployer",
    "permissions": [
      "app_project_get",
      "app_project_resourcecreate",
      "app_project_resourceupdate"
    ],
    "metadata": {
      "description": "Can deploy resources but cannot delete"
    }
  }'

Important: Specify the namespace as app/project to create project-level permissions.

State Management

Disabling a Project

Temporarily suspend access to a project without deleting it. Resources remain intact but become inaccessible.

curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/disable' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data '{}'

Authorization Required: User must have app_project_administer permission (Owner role) or custom role with delete permission at app/project namespace.

Enabling a Project

Restore access to a disabled project.

curl -L -X POST 'https://frontier.example.com/v1beta1/projects/{project_id}/enable' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  --data '{}'

Disabling a project:

Does not delete policies, resources, or users
Blocks all access to project resources
Can be used for maintenance windows or security holds
Can be reversed by re-enabling

Deleting a Project

Permanently delete a project and all associated resources.

curl -L -X DELETE 'https://frontier.example.com/v1beta1/projects/{project_id}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

This action cannot be undone!Deleting a project permanently removes:

All resources within the project
All policies associated with the project
All access grants to project resources

Users and groups are NOT deleted but lose access to the project’s resources.

Authorization Required: User must have app_project_administer permission (Owner role).

Common Patterns

Environment Separation
Team Separation
Product Separation

Organization: Acme Corp
├── Project: Production
│   └── Resources: prod-db, prod-api, prod-cache
├── Project: Staging
│   └── Resources: staging-db, staging-api, staging-cache
└── Project: Development
    └── Resources: dev-db, dev-api, dev-cache

Create separate projects for each environment to isolate access and resources.

Organization: Tech Company
├── Project: Platform Team
│   └── Resources: infrastructure, monitoring, deployment
├── Project: Backend Team
│   └── Resources: apis, services, databases
└── Project: Frontend Team
    └── Resources: web-apps, mobile-apps

Organize projects by team to match your organizational structure.

Organization: SaaS Company
├── Project: Product A
│   └── Resources: product-a-api, product-a-db
├── Project: Product B
│   └── Resources: product-b-api, product-b-db
└── Project: Shared Services
    └── Resources: auth-service, payment-service

Create projects per product with a shared services project for common resources.

Best Practices

Descriptive Naming

Use clear, consistent naming conventions that indicate the project’s purpose, environment, or team.

Metadata Usage

Leverage metadata to store additional context like cost centers, owners, or custom tags for reporting.

Least Privilege

Grant the minimum permissions necessary. Use viewer roles by default and elevate only when needed.

Regular Reviews

Periodically audit project members and their access levels to ensure appropriate permissions.

Next Steps

Manage Resources

Add resources to your projects

Manage Groups

Create groups for easier access management

Configure Policies

Set up fine-grained access control

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Overview

​Project Model

​Roles and Permissions

​Access Control Patterns

Project-Level Access

Resource-Level Access

​Creating a Project

​Listing Projects

​List All Projects (Admin)

​List Organization Projects

​Getting Project Details

​Updating a Project

​Managing Project Members

​Listing Project Users

​Listing Project Admins

​Creating Project Policies

​Create Custom Roles

​State Management

​Disabling a Project

​Enabling a Project

​Deleting a Project

​Common Patterns

​Best Practices

Descriptive Naming

Metadata Usage

Least Privilege

Regular Reviews

​Next Steps

Manage Resources

Manage Groups

Configure Policies

Build docs developers (and LLMs) love

Overview

Project Model

Roles and Permissions

Access Control Patterns

Creating a Project

Listing Projects

List All Projects (Admin)

List Organization Projects

Getting Project Details

Updating a Project

Managing Project Members

Listing Project Users

Listing Project Admins

Creating Project Policies

Create Custom Roles

State Management

Disabling a Project

Enabling a Project

Deleting a Project

Common Patterns

Best Practices

Next Steps