[New] Project Portfolio Settings API

English Forum Developers & API Changelog
,
1

[New] Project Portfolio Settings’s New Endpoints and Webhooks

Summary

We are introducing the project_portfolio_setting resource to the Asana API. This new resource represents the relationship between a portfolio and a project it contains, specifically exposing the ability to manage permission inheritance. This is designed as a standalone resource to model the many-to-many relationship between projects and portfolios. This architecture ensures that settings remain scoped to a specific project-portfolio pair and provides a scalable foundation for future relationship-based configurations.

Previously, the “permission syncing” setting was only accessible via the Asana web app’s share modal. By exposing this via the API, developers can now programmatically control whether portfolio members automatically inherit access to projects within those portfolios.

Who is affected

This is a purely additive change and is not a breaking change.

  • Integration Developers: If you manage project memberships or portfolio-based workflows, you now have granular control over access flows.
  • Automation Tools: You can now subscribe to webhooks to react when a project is added to a portfolio or when inheritance settings are toggled.

Usage

The project_portfolio_setting Object

Field Type Description
gid string Globally unique identifier.
is_access_control_inherited boolean Whether access levels are inherited from portfolio to project.
project object The project contained in the portfolio (returns gid, name).
portfolio object The portfolio containing the project (returns gid, name).

Endpoints

Method Endpoint Description
GET /project_portfolio_settings/{pps_gid} Returns a single setting record.
PUT /project_portfolio_settings/{pps_gid} Updates the is _access_control_inherited field.
GET /projects/{project_gid}/project_portfolio_settings Lists all project portfolio settings objects associated with a particular project.
GET /portfolios/{portfolio_gid}/project_portfolio_settings Lists all project portfolio settings objects associated with a particular portfolio.

Example: List inheritance settings for a project

GET /api/1.0/projects/67890/project_portfolio_settings

{
  "data": [
    {
      "gid": "12345",
      "resource_type": "project_portfolio_setting",
      "project": {
        "gid": "67890",
        "resource_type": "project",
        "name": "My Project"
      },
      "portfolio": {
        "gid": "11111",
        "resource_type": "portfolio",
        "name": "Q1 Portfolio"
      },
      "is_access_control_inherited": true,
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "next_page": null
}

Example: Enable permission inheritance

PUT /api/1.0/project_portfolio_settings/12345

{
  "data": {
    "gid": "12345",
    "resource_type": "project_portfolio_setting",
    "project": {
      "gid": "67890",
      "resource_type": "project",
      "name": "My Project"
    },
    "portfolio": {
      "gid": "11111",
      "resource_type": "portfolio",
      "name": "Q1 Portfolio"
    },
    "is_access_control_inherited": true,
    "created_at": "2026-01-15T12:00:00.000Z"
  }
}

Example: Get PPS Object

GET /api/1.0/project_portfolio_settings/12345

{
  "data": {
    "gid": "12345",
    "resource_type": "project_portfolio_setting",
    "project": { "gid": "67890", "name": "My Project" },
    "portfolio": { "gid": "11111", "name": "Q1 Portfolio" },
    "is_access_control_inherited": true,
    "created_at": "2026-01-15T12:00:00.000Z"
  }
}

Webhooks

You can now subscribe to project_portfolio_setting targets for the following events:

  • added: Triggered when a project is added to a portfolio setting.
  • changed: Triggered when is_access_control_inherited is toggled.
  • removed: Triggered when a project is removed from a portfolio setting.

Implementation Details & Permissions

  • Role Mapping: When enabled, roles map 1:1 (e.g., a Portfolio Editor becomes a Project Editor).
  • Authorization: Only Project Admins can toggle the is_access_control_inherited field. Project admins can toggle this even for portfolios they cannot see (similar to private team logic).
  • Defaults: By default, inheritance is set to false for new connections.

Timeline

The endpoints are now live for all organizations.

Key Resources

3 Likes