Custom Roles

Custom roles let you assign specific scopes, a name, and a description to a role. Scopes are additive. A custom role starts from a baseline of read access to the catalog and adds only the scopes you list. It does not remove access that the baseline already provides.

Use the GraphQL API to create, update, read, and delete custom roles. Some resources are only available on certain plans or with certain features enabled, so the full list your account can grant may be a subset of the table below.

Resource	Available actions
Component	`write_if_owner`, `write_if_unowned`, `write_all`
Document	`read`, `write`
EntityObject (Systems, Domains)	`read`, `write_all`
Integration	`write_if_owner`, `write_if_unowned`, `write_all`
Secret	`write_if_owner`, `write_all`
Team	`write_metadata_if_member`, `write_if_manager`, `write_all`
Standards (Rubric, Checks, Scorecards, Campaigns, Filters, Categories & Levels)	`write`

Creating a custom role

mutation CreateCustomRole($input: CustomRoleInput!) {
  customRoleCreate(input: $input) {
    customRole {
      id
      slug
      name
      scopes {
        resource
        actions {
          name
        }
      }
    }
    errors {
      message
      path
    }
  }
}

# Variables
# {
#   input: {
#     name: "Standards Editor",
#     description: "Can manage Checks, Rubrics, Scorecards, and Campaigns, read-only elsewhere",
#     scopes: [
#       { resource: "Standards", actions: ["write"] }
#     ]
#   }
# }

Assign a custom role to a user

mutation UpdateCustomRole($customRole: IdentifierInput!, $input: CustomRoleInput!) {
  customRoleUpdate(customRole: $customRole, input: $input) {
    customRole {
      id
      slug
      name
      scopes {
        resource
        actions {
          name
        }
      }
    }
    errors {
      message
      path
    }
  }
}

# Variables
# {
#   customRole: { alias: "standards-editor" },
#   input: {
#     name: "Standards Editor",
#     description: "Can manage Checks, Rubrics, Scorecards, and Campaigns, plus documents",
#     scopes: [
#       { resource: "Standards", actions: ["write"] },
#       { resource: "Document", actions: ["read", "write"] }
#     ]
#   }
# }

Deleting a custom role

mutation DeleteCustomRole($customRole: IdentifierInput!) {
  customRoleDelete(customRole: $customRole) {
    deletedCustomRoleId
    deletedCustomRoleAlias
    errors {
      message
      path
    }
  }
}

# Variables
# {
#   customRole: { alias: "standards-editor" }
# }

The following examples show how to manage custom roles.

Example: Integrations Admin

Here's a worked example that grants write access to Integrations owned by (or unowned by) the user's teams, plus the supporting access an integration owner typically needs — managing secrets they own, managing teams they manage, and read access to documents and systems/domains:

# Variables for CreateCustomRole
{
  "input": {
    "name": "Integrations Admin",
    "description": "Write access to Integrations and Secrets they own, and unowned Integrations. Can manage teams they are a manager of. Team-Member level access to all other resources.",
    "scopes": [
      { "resource": "Component", "actions": ["write_if_owner", "write_if_unowned"] },
      { "resource": "Document", "actions": ["read"] },
      { "resource": "EntityObject", "actions": ["read"] },
      { "resource": "Integration", "actions": ["write_if_owner", "write_if_unowned"] },
      { "resource": "Secret", "actions": ["write_if_owner"] },
      { "resource": "Team", "actions": ["write_if_manager"] }
    ]
  }
}

Standards Editor

Manage the Rubric, Checks, Scorecards, and Campaigns without account settings access.

{
  "input": {
    "name": "Standards Editor",
    "description": "Can manage Checks, Rubrics, Scorecards, and Campaigns. Baseline access elsewhere.",
    "scopes": [
      { "resource": "Standards", "actions": ["write"] }
    ]
  }
}

Team Manager

Manage the teams they are assigned to manage, without the broad User role that permits deleting any team.

{
  "input": {
    "name": "Team Manager",
    "description": "Manage teams they are a manager of. Team-Member access elsewhere.",
    "scopes": [
      { "resource": "Team", "actions": ["write_if_manager"] },
      { "resource": "Component", "actions": ["write_if_owner"] }
    ]
  }
}