# Organization policies

## List policies

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

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization policies.","name":"organization_iam_policy"}],"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":{"PolicyList":{"type":"object","title":"PolicyList","properties":{"results":{"type":"array","description":"List of IAM policies.","items":{"$ref":"#/components/schemas/iam_policy"}}},"required":["results"]},"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"}},"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-policies":{"get":{"description":"List the IAM policies that are defined for this organization.","operationId":"listOrganizationPolicies","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/direction"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PolicyList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"401":{"$ref":"#/components/responses/unauthorized"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"List policies","tags":["organization_iam_policy"]}}}}
```

## Create policy

> Create a new IAM policy for this organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization policies.","name":"organization_iam_policy"}],"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":{"CreatePolicy":{"type":"object","title":"CreatePolicy","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/iam_policy_properties-name"},"description":{"$ref":"#/components/schemas/description"},"definitions":{"$ref":"#/components/schemas/definitions"},"metadata":{"type":"object","description":"Metadata for the IAM Role.","additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"},"apps":{"$ref":"#/components/schemas/apps"},"groups":{"$ref":"#/components/schemas/groups"}}}},"required":["name","definitions"]},"iam_policy_properties-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},"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":{"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"]},"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":{"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-policies":{"post":{"description":"Create a new IAM policy for this organization.","operationId":"createOrganizationPolicy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicy"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/iam_policy"}}},"description":"Created"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create policy","tags":["organization_iam_policy"]}}}}
```

## Get policy

> Retrieve a single IAM policy.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization policies.","name":"organization_iam_policy"}],"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_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"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/iam-policies/{policyId}":{"get":{"description":"Retrieve a single IAM policy.","operationId":"getOrganizationPolicy","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/iam_policy"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get policy","tags":["organization_iam_policy"]}}}}
```

## Delete policy

> Remove an IAM policy from the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization policies.","name":"organization_iam_policy"}],"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":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/iam-policies/{policyId}":{"delete":{"description":"Remove an IAM policy from the organization.","operationId":"deleteOrganizationPolicy","responses":{"204":{"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cannot remove policy because it's still in use"},"404":{"$ref":"#/components/responses/notFound"},"410":{"$ref":"#/components/responses/notFound"}},"summary":"Delete policy","tags":["organization_iam_policy"]}}}}
```

## Update policy

> Update an IAM policy's properties.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization policies.","name":"organization_iam_policy"}],"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":{"UpdatePolicy":{"type":"object","title":"UpdatePolicy","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/iam_policy_properties-name"},"description":{"$ref":"#/components/schemas/description"},"definitions":{"$ref":"#/components/schemas/definitions"}}},"iam_policy_properties-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},"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":{"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-policies/{policyId}":{"patch":{"description":"Update an IAM policy's properties.","operationId":"updateOrganizationPolicy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePolicy"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/iam_policy"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update policy","tags":["organization_iam_policy"]}}}}
```