Update a custom role's description and statements.
curl --request PUT \ --url https://stratum.example.com/v1/iam/custom-roles/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "description": "example", "statements": [ { "principals": { "kind": "user", "ref": "example" }, "effect": "permit", "actions": [ "example" ], "notActions": [ "example" ], "resources": { "kind": "scope", "arns": [ "example" ] }, "conditions": [ { "key": "example", "op": "eq", "value": "example", "values": [ "example" ] } ] } ] }'Cedar action iam:UpdateCustomRole.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Custom role name; custom roles are addressed by name, which is unique install-wide.
Request Bodyrequired
Section titled “Request Bodyrequired”object
One authored statement. For identity
policies principal + scope are pinned by the attachment/binding
(statement omits both); for resource policies the
resource is pinned and principals selects who.
object
Who a resource-policy statement grants/denies. Only valid on resource policies; identity-policy statements omit it (the principal is pinned to the attachment target).
object
user: one user or service account. group: any member of an
IAM group. any: any authenticated principal.
project: any principal ACTING IN
the named project — the request’s project scope, not the
principal’s memberships — the AWS “share with account” shape;
what share writes on an image.
A u-/sa- id when kind is “user”; a g- group id when kind is “group”; a p- project id when kind is “project”.
Action names from the catalog. The single element “” means
any action within scope; “notActions — set exactly one.
The AWS NotAction analog: the statement applies to
every catalog action EXCEPT these. Mutually exclusive with
actions. Cannot be “*”. (NotAction with permit is broad
the builder should warn.)
object
scope = every resource in the attachment scope; arns = the listed resources (each ARN’s id may be a wildcard * or prefix*,); notArns = every resource in scope EXCEPT the listed (concrete) ARNs.
One ABAC when clause. key is a dotted context path: resource.tags.<key> or a fixed resource attribute (resource.id, resource.type, resource.projectId, resource.organizationId), or a request-context key (request.sourceIp, request.currentTime, request.mfaPresent). Scalar ops (eq, neq, stringLike) take value; set ops (in, notIn) take values; stringLike matches a *-wildcard glob; the CIDR ops (ipAddress, notIpAddress) apply only to request.sourceIp; the window ops (after, before, RFC3339 value) only to request.currentTime; request.mfaPresent takes eq/neq against "true"/"false". The catalog (GET /v1/iam/actions conditionKeys) lists supported keys + ops.
object
Dotted context path: resource.tags.
Operand for the scalar ops (eq, neq, stringLike), the CIDR ops (ipAddress, notIpAddress — a CIDR like 10.0.0.0/8 or a bare IP, valid only on request.sourceIp), the window ops (after, before — an RFC3339 timestamp, valid only on request.currentTime), and request.mfaPresent (eq/neq against “true”/“false”).
Operand set for the set-membership ops (in, notIn).
Responses
Section titled “Responses”Updated.
object
Which binding scope type the role can be granted at.
One authored statement. For identity
policies principal + scope are pinned by the attachment/binding
(statement omits both); for resource policies the
resource is pinned and principals selects who.
object
Who a resource-policy statement grants/denies. Only valid on resource policies; identity-policy statements omit it (the principal is pinned to the attachment target).
object
user: one user or service account. group: any member of an
IAM group. any: any authenticated principal.
project: any principal ACTING IN
the named project — the request’s project scope, not the
principal’s memberships — the AWS “share with account” shape;
what share writes on an image.
A u-/sa- id when kind is “user”; a g- group id when kind is “group”; a p- project id when kind is “project”.
Action names from the catalog. The single element “” means
any action within scope; “notActions — set exactly one.
The AWS NotAction analog: the statement applies to
every catalog action EXCEPT these. Mutually exclusive with
actions. Cannot be “*”. (NotAction with permit is broad
the builder should warn.)
object
scope = every resource in the attachment scope; arns = the listed resources (each ARN’s id may be a wildcard * or prefix*,); notArns = every resource in scope EXCEPT the listed (concrete) ARNs.
One ABAC when clause. key is a dotted context path: resource.tags.<key> or a fixed resource attribute (resource.id, resource.type, resource.projectId, resource.organizationId), or a request-context key (request.sourceIp, request.currentTime, request.mfaPresent). Scalar ops (eq, neq, stringLike) take value; set ops (in, notIn) take values; stringLike matches a *-wildcard glob; the CIDR ops (ipAddress, notIpAddress) apply only to request.sourceIp; the window ops (after, before, RFC3339 value) only to request.currentTime; request.mfaPresent takes eq/neq against "true"/"false". The catalog (GET /v1/iam/actions conditionKeys) lists supported keys + ops.
object
Dotted context path: resource.tags.
Operand for the scalar ops (eq, neq, stringLike), the CIDR ops (ipAddress, notIpAddress — a CIDR like 10.0.0.0/8 or a bare IP, valid only on request.sourceIp), the window ops (after, before — an RFC3339 timestamp, valid only on request.currentTime), and request.mfaPresent (eq/neq against “true”/“false”).
Operand set for the set-membership ops (in, notIn).
Generated Cedar source (read-only rendering).
Example
{ "scopeType": "organization", "statements": [ { "principals": { "kind": "user" }, "effect": "permit", "resources": { "kind": "scope" }, "conditions": [ { "op": "eq" } ] } ]}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Missing or invalid token.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Headers
Section titled “Headers”Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Resource not found.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}