Skip to main content

update-role 

dci update-role <id> [body]

Updates the name, description and/or permissions of a custom role. Only the fields present in the body change; permissions replaces the full list when present. Preset roles cannot be modified. A service account of a parent tenant can update a descendant tenant's role by setting X-Tenant-Id to that tenant's customer ID.

  • id — Role ID or name as shown by dci list-roles. Names resolve (exact, unique substring, or close typo); pass --id to force a literal ID.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Send name, description, permissions, or any combination (at least one); fields you leave out keep their value. permissions replaces the whole list and an empty list clears it; an empty description clears the description. Preset roles cannot be modified (400), and a new name must be unique among the customer's roles, preset roles included (409).

Examples​

# Rename a custom role.
dci update-role "FinOps Analyst" name: "FinOps Reader"
# Replace the role's permissions (the list you send is the whole new list, not an addition).
dci update-role <role-id> permissions: [<permission-id>, <permission-id>, <permission-id>]
# Change several fields from a JSON file.
dci update-role <role-id> < role.json
# role.json
{"name": "FinOps Reader", "description": "Read-only access to cost reports",
 "permissions": ["<permission-id>", "<permission-id>"]}

Request​

Content-Type: application/json

FieldTypeRequiredDescription
namestringThe new name of the role. Must be nonblank, contain no leading or trailing whitespace, and be unique among the customer's roles, including preset roles. Omission leaves the name unchanged.
descriptionstringThe new description of the role. An empty string clears it; omission leaves it unchanged.
permissionsarray of stringPermission IDs that replace the role's current permissions, as returned in permissions by GET /iam/v1/roles. Duplicate IDs are rejected. Input order is preserved. An empty array clears all permissions; omission leaves them unchanged.

Example body (JSON)​

{
  "name": "FinOps Analyst",
  "description": "Read-only access to cost reports and budgets",
  "permissions": [
    "oeuwhFPi8UTccU1nYjdl",
    "8zXuFyohNSiiLy2ZQ6Xu"
  ]
}
Raw JSON schema
{
  "type": "object",
  "description": "Fields allowed when updating a custom role. At least one field is required.",
  "minProperties": 1,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "not": {
        "type": "string",
        "pattern": "^[\t-\r …   - 

  　]|[\t-\r …   - 

  　]$"
      },
      "description": "The new name of the role. Must be nonblank, contain no leading or trailing whitespace, and be unique among the customer's roles, including preset roles. Omission leaves the name unchanged."
    },
    "description": {
      "type": "string",
      "description": "The new description of the role. An empty string clears it; omission leaves it unchanged."
    },
    "permissions": {
      "type": "array",
      "uniqueItems": true,
      "description": "Permission IDs that replace the role's current permissions, as returned in `permissions` by `GET /iam/v1/roles`. Duplicate IDs are rejected. Input order is preserved. An empty array clears all permissions; omission leaves them unchanged.",
      "items": {
        "type": "string"
      }
    }
  }
}

Output​

OK - Role updated.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
idstringThe unique ID of the role.
namestringThe name of the role.
typestringThe type of the role (preset or custom). One of: "preset", "custom".
descriptionstringThe description of the role. An empty string when no description is set.
customerstringThe customer ID if this is a custom role. An empty string for a preset role.
permissionsarray of stringPermission IDs in stored order. An empty array when no permissions are assigned.
childTenantEligiblebooleanWhether the owning tenant made this role available as a child tenant role.
Raw JSON schema
{
  "type": "object",
  "description": "Definition and permissions assigned to a role.",
  "required": [
    "id",
    "name",
    "type",
    "description",
    "customer",
    "permissions",
    "childTenantEligible"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the role."
    },
    "name": {
      "type": "string",
      "description": "The name of the role."
    },
    "type": {
      "type": "string",
      "enum": [
        "preset",
        "custom"
      ],
      "description": "The type of the role (preset or custom)."
    },
    "description": {
      "type": "string",
      "description": "The description of the role. An empty string when no description is set."
    },
    "customer": {
      "type": "string",
      "description": "The customer ID if this is a custom role. An empty string for a preset role."
    },
    "permissions": {
      "type": "array",
      "description": "Permission IDs in stored order. An empty array when no permissions are assigned.",
      "items": {
        "type": "string"
      }
    },
    "childTenantEligible": {
      "type": "boolean",
      "description": "Whether the owning tenant made this role available as a child tenant role."
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.
40921RESOURCE_CONFLICTThe operation conflicts with the resource's current state.
50040API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: updaterole