Managing Teams and Roles via GraphQL API in Dagster Cloud

Last updated: November 11, 2025

This article explains how to programmatically manage teams and roles in Dagster Cloud using GraphQL mutations, enabling code-based configuration instead of manual UI management.

Problem Description

Users need to manage teams and roles programmatically in Dagster Cloud, especially when scaling to multiple code locations. Manual configuration through the UI becomes inefficient and error-prone when creating new teams and roles for each code location.

Symptoms

  • Need to create multiple teams for different code locations

  • Manual role assignment becomes time-consuming at scale

  • Difficulty maintaining consistent permissions across deployments

  • Need for automated team/role creation when new code locations are added

Root Cause

Dagster Cloud's UI-based team and role management doesn't scale well for organizations with multiple code locations that need granular, location-specific permissions.

Solution

Step-by-Step Resolution

  1. Create a Team
    Use the createOrUpdateTeam mutation to create new teams:

    {
  "intent": "mutation",
  "mutationName": "createOrUpdateTeam",
  "variables": {
    "name": "data_engineering_team"
  },
  "reasoning": "Creating a new team for the data engineering code location."
}

  2. Assign Code Location-Level Roles to Teams
    Use the createOrUpdateTeamPermission mutation to assign roles scoped to specific code locations:

    {
  "intent": "mutation",
  "mutationName": "createOrUpdateTeamPermission",
  "variables": {
    "teamId": "your_team_id",
    "deploymentScope": "CODE_LOCATION",
    "locationGrants": [
      {
        "locationName": "data_pipeline_location",
        "role": "EDITOR"
      }
    ],
    "grant": true
  },
  "reasoning": "Assigning editor role to team for specific code location."
}

  3. Create Custom Roles (Optional)
    If you need custom roles beyond the default ones, use the createCustomRole mutation:

    {
  "mutationName": "createCustomRole",
  "variables": {
    "name": "Data Engineer",
    "description": "Can manage jobs and assets",
    "iconName": "gear",
    "customRoleDeploymentScope": "ALL_DEPLOYMENTS",
    "customRolePermissions": ["launchRun", "editLocation"]
  }
}

  4. Add Users to Organization
    Use the addUserToOrganization mutation to add users:

    {
  "mutationName": "addUserToOrganization",
  "variables": {
    "email": "user@example.com"
  }
}

  5. Assign User Permissions
    Use the createOrUpdateUserPermissions mutation for direct user permission assignment:

    {
  "mutationName": "createOrUpdateUserPermissions",
  "variables": {
    "userPermissionInput": {
      "userId": "user-123",
      "grant": ["launchRun"],
      "deploymentScope": "ALL_DEPLOYMENTS"
    }
  }
}

Important Notes

  • Use the base GraphQL endpoint, not the ?op= style endpoint

  • Role strings must match valid role names (e.g., "VIEWER", "EDITOR", "ADMIN")

  • You need the teamId to assign permissions - retrieve it via query first

  • You can specify customRoleId when using custom roles instead of predefined ones

Implement these GraphQL mutations in your infrastructure-as-code setup to automatically create teams and assign appropriate permissions when new code locations are deployed. This ensures consistent permission management and reduces manual configuration errors.

Related Documentation