Skip to main content

update-service-account 

dci update-service-account [body] [flags]

Partially updates a service account with an application/merge-patch+json body (RFC 7396). Omitted or null fields stay unchanged; an explicit empty string clears description. permissions replaces the whole list, and [] removes every permission. With dryRun=true the request goes through the same checks as a real update (If-Match, name bounds and uniqueness, permission names, caller scope) and returns the service account as it would look after the patch, without changing anything. Requires the serviceAccountManager permission.

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

Request​

Content-Type: application/merge-patch+json

FieldTypeRequiredDescription
namestringNew name, unique among the customer's service accounts. Leading or trailing whitespace returns 400.
descriptionstringNew free-text description. null leaves it unchanged; an explicit empty string clears it.
permissionsarray of stringReplaces the whole permission list. An unknown name returns 422.

Example body (JSON)​

{
  "permissions": [
    "cloudAnalyticsReadOnly"
  ]
}
Raw JSON schema
{
  "type": "object",
  "description": "Fields to change on a service account, as a JSON Merge Patch document.",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "New name, unique among the customer's service accounts. Leading or trailing whitespace returns `400`.",
      "example": "terraform-ci"
    },
    "description": {
      "type": "string",
      "nullable": true,
      "description": "New free-text description. `null` leaves it unchanged; an explicit empty string clears it.",
      "example": "Manages DoiT resources from CI"
    },
    "permissions": {
      "type": "array",
      "nullable": true,
      "description": "Replaces the whole permission list. An unknown name returns `422`.",
      "items": {
        "type": "string"
      }
    }
  }
}

Flags​

FlagTypeDefaultExampleDescription
--dry-runbooleanfalseIf true, validates the request and returns the would-be result without applying it. The response then carries the X-Dry-Run header.

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

OK - Service account updated, or previewed when dryRun=true (the body is the merged result, and etag is still the current one).

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

FieldTypeDescription
idstringService account ID. null only on a dry-run create.
customerIdstringID of the customer that owns the service account.
namestringName, unique among the customer's service accounts.
descriptionstringFree-text description.
permissionsarray of stringPlatform permission names in camelCase, as shown in the DoiT console role editor.
createdBystringDisplay name of the user who created the service account. null when unknown or when the service account was created with a service account token.
createdByEmailstringEmail of the user who created the service account. null when unknown or when the service account was created with a service account token.
createdByUserIdstringID of the user who created the service account. null when unknown or when the service account was created with a service account token.
createTimestring (date-time)When the service account was created.
updateTimestring (date-time)When the service account was last changed.
etagstringCurrent version of the service account. Send it in If-Match to update or delete.

Example response (--output json)​

{
  "id": "Lq3nO9rM5wS2tU0xY4zA",
  "customerId": "Kp2mN8qL4vR0sT1wX3yZ",
  "name": "terraform-ci",
  "description": "Manages DoiT resources from CI",
  "permissions": [
    "cloudAnalyticsReadOnly"
  ],
  "createdBy": "Jane Doe",
  "createdByEmail": "[email protected]",
  "createdByUserId": "Ab1cD2eF3gH4iJ5kL6mN",
  "createTime": "2026-09-01T08:00:00Z",
  "updateTime": "2026-09-02T09:30:00Z",
  "etag": "9b2e4d6f8a0c1e3b5d7f9a1c3e5b7d9f1a3c5e7a9b1d3f5a7c9e1b3d5f7a9c1e"
}
Raw JSON schema
{
  "type": "object",
  "description": "A non-human identity owned by a customer. Its API tokens authenticate with exactly the permissions listed here.",
  "required": [
    "id",
    "customerId",
    "name",
    "description",
    "permissions",
    "createdBy",
    "createdByEmail",
    "createdByUserId",
    "createTime",
    "updateTime",
    "etag"
  ],
  "properties": {
    "id": {
      "type": "string",
      "nullable": true,
      "readOnly": true,
      "description": "Service account ID. `null` only on a dry-run create.",
      "example": "Lq3nO9rM5wS2tU0xY4zA"
    },
    "customerId": {
      "type": "string",
      "readOnly": true,
      "description": "ID of the customer that owns the service account.",
      "example": "Kp2mN8qL4vR0sT1wX3yZ"
    },
    "name": {
      "type": "string",
      "description": "Name, unique among the customer's service accounts."
    },
    "description": {
      "type": "string",
      "description": "Free-text description."
    },
    "permissions": {
      "type": "array",
      "description": "Platform permission names in camelCase, as shown in the DoiT console role editor.",
      "items": {
        "type": "string"
      }
    },
    "createdBy": {
      "type": "string",
      "nullable": true,
      "readOnly": true,
      "description": "Display name of the user who created the service account. `null` when unknown or when the service account was created with a service account token."
    },
    "createdByEmail": {
      "type": "string",
      "nullable": true,
      "readOnly": true,
      "description": "Email of the user who created the service account. `null` when unknown or when the service account was created with a service account token."
    },
    "createdByUserId": {
      "type": "string",
      "nullable": true,
      "readOnly": true,
      "description": "ID of the user who created the service account. `null` when unknown or when the service account was created with a service account token."
    },
    "createTime": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "readOnly": true,
      "description": "When the service account was created."
    },
    "updateTime": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "readOnly": true,
      "description": "When the service account was last changed."
    },
    "etag": {
      "type": "string",
      "nullable": true,
      "readOnly": true,
      "description": "Current version of the service account. Send it in `If-Match` to update or delete."
    }
  }
}

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
400, 42230VALIDATION_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.
412, 415, 4281API_ERRORThe request failed; the printed error message has details.
50040API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: updateserviceaccount