# Organization roles

## List roles

> List the IAM roles that are defined for this organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization roles.","name":"organization_iam_role"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"limit":{"name":"limit","description":"Limits the number of results to return","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"cursor":{"name":"pageToken","description":"Pagination token that keeps of track of the current position in the list","in":"query","schema":{"type":"string"}},"direction":{"name":"reverse","description":"Order in which to retrieve the results","in":"query","schema":{"type":"boolean","default":false}}},"schemas":{"RoleList":{"type":"object","title":"RoleList","properties":{"results":{"type":"array","description":"List of roles.","items":{"$ref":"#/components/schemas/iam_role"}}},"required":["results"]},"iam_role":{"type":"object","title":"Role","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the role.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization to which this role belongs.","format":"uuid"},"name":{"type":"string","description":"Role name."},"description":{"type":"string","description":"Role description."},"type":{"type":"string","description":"Whether this role is managed by MessageBird or by the organization.","enum":["organization","managed"]},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"oneOf":[{"$ref":"#/components/schemas/iam_policy"},{"$ref":"#/components/schemas/iam_policy_ref"}]}},"usersDependencyCount":{"type":"integer","description":"The number of users this role is assigned to.","minimum":0},"accessKeysDependencyCount":{"type":"integer","description":"The number of access keys this role is assigned to.","minimum":0},"createdAt":{"type":"string","format":"date-time","description":"When this role was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this role was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Role.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"}}},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}},"required":["id","name","type","policies","usersDependencyCount","accessKeysDependencyCount","createdAt","updatedAt"]},"iam_policy":{"type":"object","title":"Policy","description":"The IAM policy record.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"name":{"type":"string","description":"IAM Policy name."},"description":{"type":"string","description":"IAM Policy description."},"definitions":{"type":"array","title":"PolicyDefinitions","description":"List of IAM Policy definitions.","items":{"type":"object","title":"PolicyDefinition","description":"An access rule for a specific resource and action.","additionalProperties":false,"properties":{"effect":{"type":"string","enum":["allow","deny"],"description":"The outcome of the definition if a combination of the resources and actions match."},"resources":{"type":"array","description":"A list of resources","items":{"type":"string"}},"actions":{"type":"array","description":"A list of actions","items":{"type":"string","enum":["any","view","create","delete","update"]}},"conditionsAll":{"type":"array","items":{"type":"object","title":"PolicyConditionAll","additionalProperties":false,"properties":{"any":{"type":"object","title":"PolicyConditionAny","additionalProperties":{"type":"object","additionalProperties":{"type":"string","maxLength":256}}}}}}},"required":["effect","resources","actions"]},"minItems":1,"maxItems":240},"rolesDependencyCount":{"type":"integer","description":"The number of IAM Roles that depend on this IAM policy.","minimum":0},"usersDependencyCount":{"type":"integer","description":"The number of users that depend on this IAM policy.","minimum":0},"scope":{"type":"string","description":"The scope to which this policy applies.","enum":["organization","root"]},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"createdAt":{"type":"string","format":"date-time","description":"When the IAM Policy was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the IAM Policy was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Policy.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"},"apps":{"$ref":"#/components/schemas/apps"},"groups":{"$ref":"#/components/schemas/groups"}}}},"required":["id","name","definitions","scope","createdAt","updatedAt"]},"clouds":{"type":"array","nullable":true,"items":{"type":"string","enum":["platform","customer-service","marketing","process-automation","ai-hub","payments","developer","admin","hr","sales","expenses"]}},"apps":{"type":"array","nullable":true,"items":{"type":"string","enum":["inbox","campaigns","flows","journeys","studio","analytics","channels","numbers","bots","contacts"]}},"groups":{"type":"array","nullable":true,"items":{"type":"string"}},"iam_policy_ref":{"type":"object","title":"PolicyRef","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/iam_policy_properties-id"},"type":{"$ref":"#/components/schemas/type"}},"required":["id","type"]},"iam_policy_properties-id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"iam_action":{"type":"object","title":"Action","properties":{"name":{"type":"string","description":"The name of the action."},"type":{"type":"string","description":"The type that the action belongs to."}},"required":["name","type"]},"responseBody":{"type":"object","title":"PaginatedList","description":"A list of results that supports pagination.","properties":{"nextPageToken":{"type":"string","description":"The token to fetch the next page of results. If empty, there are no more results to fetch."}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"unauthorized request"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/iam-roles":{"get":{"description":"List the IAM roles that are defined for this organization.","operationId":"listRoles","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/direction"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RoleList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"401":{"$ref":"#/components/responses/unauthorized"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"List roles","tags":["organization_iam_role"]}}}}
```

## Create role

> Create a new IAM role for this organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization roles.","name":"organization_iam_role"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateRole":{"type":"object","title":"CreateRole","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/iam_role_properties-name"},"description":{"$ref":"#/components/schemas/properties-description"},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"$ref":"#/components/schemas/iam_policy_ref"},"minItems":0,"maxItems":32},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}},"required":["name","policies"]},"iam_role_properties-name":{"type":"string","description":"Role name."},"properties-description":{"type":"string","description":"Role description."},"iam_policy_ref":{"type":"object","title":"PolicyRef","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/iam_policy_properties-id"},"type":{"$ref":"#/components/schemas/type"}},"required":["id","type"]},"iam_policy_properties-id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"iam_action":{"type":"object","title":"Action","properties":{"name":{"type":"string","description":"The name of the action."},"type":{"type":"string","description":"The type that the action belongs to."}},"required":["name","type"]},"iam_role":{"type":"object","title":"Role","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the role.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization to which this role belongs.","format":"uuid"},"name":{"type":"string","description":"Role name."},"description":{"type":"string","description":"Role description."},"type":{"type":"string","description":"Whether this role is managed by MessageBird or by the organization.","enum":["organization","managed"]},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"oneOf":[{"$ref":"#/components/schemas/iam_policy"},{"$ref":"#/components/schemas/iam_policy_ref"}]}},"usersDependencyCount":{"type":"integer","description":"The number of users this role is assigned to.","minimum":0},"accessKeysDependencyCount":{"type":"integer","description":"The number of access keys this role is assigned to.","minimum":0},"createdAt":{"type":"string","format":"date-time","description":"When this role was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this role was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Role.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"}}},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}},"required":["id","name","type","policies","usersDependencyCount","accessKeysDependencyCount","createdAt","updatedAt"]},"iam_policy":{"type":"object","title":"Policy","description":"The IAM policy record.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"name":{"type":"string","description":"IAM Policy name."},"description":{"type":"string","description":"IAM Policy description."},"definitions":{"type":"array","title":"PolicyDefinitions","description":"List of IAM Policy definitions.","items":{"type":"object","title":"PolicyDefinition","description":"An access rule for a specific resource and action.","additionalProperties":false,"properties":{"effect":{"type":"string","enum":["allow","deny"],"description":"The outcome of the definition if a combination of the resources and actions match."},"resources":{"type":"array","description":"A list of resources","items":{"type":"string"}},"actions":{"type":"array","description":"A list of actions","items":{"type":"string","enum":["any","view","create","delete","update"]}},"conditionsAll":{"type":"array","items":{"type":"object","title":"PolicyConditionAll","additionalProperties":false,"properties":{"any":{"type":"object","title":"PolicyConditionAny","additionalProperties":{"type":"object","additionalProperties":{"type":"string","maxLength":256}}}}}}},"required":["effect","resources","actions"]},"minItems":1,"maxItems":240},"rolesDependencyCount":{"type":"integer","description":"The number of IAM Roles that depend on this IAM policy.","minimum":0},"usersDependencyCount":{"type":"integer","description":"The number of users that depend on this IAM policy.","minimum":0},"scope":{"type":"string","description":"The scope to which this policy applies.","enum":["organization","root"]},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"createdAt":{"type":"string","format":"date-time","description":"When the IAM Policy was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the IAM Policy was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Policy.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"},"apps":{"$ref":"#/components/schemas/apps"},"groups":{"$ref":"#/components/schemas/groups"}}}},"required":["id","name","definitions","scope","createdAt","updatedAt"]},"clouds":{"type":"array","nullable":true,"items":{"type":"string","enum":["platform","customer-service","marketing","process-automation","ai-hub","payments","developer","admin","hr","sales","expenses"]}},"apps":{"type":"array","nullable":true,"items":{"type":"string","enum":["inbox","campaigns","flows","journeys","studio","analytics","channels","numbers","bots","contacts"]}},"groups":{"type":"array","nullable":true,"items":{"type":"string"}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden operation"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"alreadyExists":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The resource already exists"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/iam-roles":{"post":{"description":"Create a new IAM role for this organization.","operationId":"createRole","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRole"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/iam_role"}}},"description":"Created"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/alreadyExists"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create role","tags":["organization_iam_role"]}}}}
```

## Get role

> Retrieve a single IAM role.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization roles.","name":"organization_iam_role"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"iam_role":{"type":"object","title":"Role","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the role.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization to which this role belongs.","format":"uuid"},"name":{"type":"string","description":"Role name."},"description":{"type":"string","description":"Role description."},"type":{"type":"string","description":"Whether this role is managed by MessageBird or by the organization.","enum":["organization","managed"]},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"oneOf":[{"$ref":"#/components/schemas/iam_policy"},{"$ref":"#/components/schemas/iam_policy_ref"}]}},"usersDependencyCount":{"type":"integer","description":"The number of users this role is assigned to.","minimum":0},"accessKeysDependencyCount":{"type":"integer","description":"The number of access keys this role is assigned to.","minimum":0},"createdAt":{"type":"string","format":"date-time","description":"When this role was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this role was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Role.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"}}},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}},"required":["id","name","type","policies","usersDependencyCount","accessKeysDependencyCount","createdAt","updatedAt"]},"iam_policy":{"type":"object","title":"Policy","description":"The IAM policy record.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"name":{"type":"string","description":"IAM Policy name."},"description":{"type":"string","description":"IAM Policy description."},"definitions":{"type":"array","title":"PolicyDefinitions","description":"List of IAM Policy definitions.","items":{"type":"object","title":"PolicyDefinition","description":"An access rule for a specific resource and action.","additionalProperties":false,"properties":{"effect":{"type":"string","enum":["allow","deny"],"description":"The outcome of the definition if a combination of the resources and actions match."},"resources":{"type":"array","description":"A list of resources","items":{"type":"string"}},"actions":{"type":"array","description":"A list of actions","items":{"type":"string","enum":["any","view","create","delete","update"]}},"conditionsAll":{"type":"array","items":{"type":"object","title":"PolicyConditionAll","additionalProperties":false,"properties":{"any":{"type":"object","title":"PolicyConditionAny","additionalProperties":{"type":"object","additionalProperties":{"type":"string","maxLength":256}}}}}}},"required":["effect","resources","actions"]},"minItems":1,"maxItems":240},"rolesDependencyCount":{"type":"integer","description":"The number of IAM Roles that depend on this IAM policy.","minimum":0},"usersDependencyCount":{"type":"integer","description":"The number of users that depend on this IAM policy.","minimum":0},"scope":{"type":"string","description":"The scope to which this policy applies.","enum":["organization","root"]},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"createdAt":{"type":"string","format":"date-time","description":"When the IAM Policy was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the IAM Policy was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Policy.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"},"apps":{"$ref":"#/components/schemas/apps"},"groups":{"$ref":"#/components/schemas/groups"}}}},"required":["id","name","definitions","scope","createdAt","updatedAt"]},"clouds":{"type":"array","nullable":true,"items":{"type":"string","enum":["platform","customer-service","marketing","process-automation","ai-hub","payments","developer","admin","hr","sales","expenses"]}},"apps":{"type":"array","nullable":true,"items":{"type":"string","enum":["inbox","campaigns","flows","journeys","studio","analytics","channels","numbers","bots","contacts"]}},"groups":{"type":"array","nullable":true,"items":{"type":"string"}},"iam_policy_ref":{"type":"object","title":"PolicyRef","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/iam_policy_properties-id"},"type":{"$ref":"#/components/schemas/type"}},"required":["id","type"]},"iam_policy_properties-id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"iam_action":{"type":"object","title":"Action","properties":{"name":{"type":"string","description":"The name of the action."},"type":{"type":"string","description":"The type that the action belongs to."}},"required":["name","type"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/iam-roles/{roleId}":{"get":{"description":"Retrieve a single IAM role.","operationId":"getRole","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/iam_role"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get role","tags":["organization_iam_role"]}}}}
```

## Delete role

> Remove an IAM role from the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization roles.","name":"organization_iam_role"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden operation"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The HTTP 409 Conflict response status code indicates a request conflict with current state of the target resource."}}},"paths":{"/organizations/{organizationId}/iam-roles/{roleId}":{"delete":{"description":"Remove an IAM role from the organization.","operationId":"deleteRole","responses":{"204":{"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cannot remove role because it's still in use"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"},"410":{"$ref":"#/components/responses/notFound"}},"summary":"Delete role","tags":["organization_iam_role"]}}}}
```

## Update role

> Update an IAM role's properties.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization roles.","name":"organization_iam_role"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateRole":{"type":"object","title":"UpdateRole","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/iam_role_properties-name"},"description":{"$ref":"#/components/schemas/properties-description"},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"$ref":"#/components/schemas/iam_policy_ref"},"minItems":0,"maxItems":32},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}}},"iam_role_properties-name":{"type":"string","description":"Role name."},"properties-description":{"type":"string","description":"Role description."},"iam_policy_ref":{"type":"object","title":"PolicyRef","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/iam_policy_properties-id"},"type":{"$ref":"#/components/schemas/type"}},"required":["id","type"]},"iam_policy_properties-id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"iam_action":{"type":"object","title":"Action","properties":{"name":{"type":"string","description":"The name of the action."},"type":{"type":"string","description":"The type that the action belongs to."}},"required":["name","type"]},"iam_role":{"type":"object","title":"Role","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the role.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization to which this role belongs.","format":"uuid"},"name":{"type":"string","description":"Role name."},"description":{"type":"string","description":"Role description."},"type":{"type":"string","description":"Whether this role is managed by MessageBird or by the organization.","enum":["organization","managed"]},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"oneOf":[{"$ref":"#/components/schemas/iam_policy"},{"$ref":"#/components/schemas/iam_policy_ref"}]}},"usersDependencyCount":{"type":"integer","description":"The number of users this role is assigned to.","minimum":0},"accessKeysDependencyCount":{"type":"integer","description":"The number of access keys this role is assigned to.","minimum":0},"createdAt":{"type":"string","format":"date-time","description":"When this role was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this role was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Role.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"}}},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}},"required":["id","name","type","policies","usersDependencyCount","accessKeysDependencyCount","createdAt","updatedAt"]},"iam_policy":{"type":"object","title":"Policy","description":"The IAM policy record.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"name":{"type":"string","description":"IAM Policy name."},"description":{"type":"string","description":"IAM Policy description."},"definitions":{"type":"array","title":"PolicyDefinitions","description":"List of IAM Policy definitions.","items":{"type":"object","title":"PolicyDefinition","description":"An access rule for a specific resource and action.","additionalProperties":false,"properties":{"effect":{"type":"string","enum":["allow","deny"],"description":"The outcome of the definition if a combination of the resources and actions match."},"resources":{"type":"array","description":"A list of resources","items":{"type":"string"}},"actions":{"type":"array","description":"A list of actions","items":{"type":"string","enum":["any","view","create","delete","update"]}},"conditionsAll":{"type":"array","items":{"type":"object","title":"PolicyConditionAll","additionalProperties":false,"properties":{"any":{"type":"object","title":"PolicyConditionAny","additionalProperties":{"type":"object","additionalProperties":{"type":"string","maxLength":256}}}}}}},"required":["effect","resources","actions"]},"minItems":1,"maxItems":240},"rolesDependencyCount":{"type":"integer","description":"The number of IAM Roles that depend on this IAM policy.","minimum":0},"usersDependencyCount":{"type":"integer","description":"The number of users that depend on this IAM policy.","minimum":0},"scope":{"type":"string","description":"The scope to which this policy applies.","enum":["organization","root"]},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"createdAt":{"type":"string","format":"date-time","description":"When the IAM Policy was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the IAM Policy was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Policy.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"},"apps":{"$ref":"#/components/schemas/apps"},"groups":{"$ref":"#/components/schemas/groups"}}}},"required":["id","name","definitions","scope","createdAt","updatedAt"]},"clouds":{"type":"array","nullable":true,"items":{"type":"string","enum":["platform","customer-service","marketing","process-automation","ai-hub","payments","developer","admin","hr","sales","expenses"]}},"apps":{"type":"array","nullable":true,"items":{"type":"string","enum":["inbox","campaigns","flows","journeys","studio","analytics","channels","numbers","bots","contacts"]}},"groups":{"type":"array","nullable":true,"items":{"type":"string"}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden operation"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/iam-roles/{roleId}":{"patch":{"description":"Update an IAM role's properties.","operationId":"updateRole","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRole"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/iam_role"}}},"description":"OK"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update role","tags":["organization_iam_role"]}}}}
```