Organization roles

Roles group one or more organization policies, and can be assigned to organization users and access keys.

List roles

get

List the IAM roles that are defined for this organization.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10

pageTokenstringOptional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

Responses

200

application/json

Responseall of

401

unauthorized request

application/json

404

Resource not found

application/json

get

/organizations/{organizationId}/iam-roles

GET /organizations/{organizationId}/iam-roles HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "type": "organization",
      "policies": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "description": "text",
          "definitions": [
            {
              "effect": "allow",
              "resources": [
                "text"
              ],
              "actions": [
                "any"
              ],
              "conditionsAll": [
                {
                  "any": {
                    "ANY_ADDITIONAL_PROPERTY": {
                      "ANY_ADDITIONAL_PROPERTY": "text"
                    }
                  }
                }
              ]
            }
          ],
          "rolesDependencyCount": 1,
          "usersDependencyCount": 1,
          "scope": "organization",
          "type": "managed",
          "createdAt": "2025-11-06T01:43:01.195Z",
          "updatedAt": "2025-11-06T01:43:01.195Z",
          "metadata": {
            "clouds": [
              "platform"
            ],
            "apps": [
              "inbox"
            ],
            "groups": [
              "text"
            ]
          }
        }
      ],
      "usersDependencyCount": 1,
      "accessKeysDependencyCount": 1,
      "createdAt": "2025-11-06T01:43:01.195Z",
      "updatedAt": "2025-11-06T01:43:01.195Z",
      "metadata": {
        "clouds": [
          "platform"
        ]
      },
      "actions": [
        {
          "name": "text",
          "type": "text"
        }
      ]
    }
  ],
  "nextPageToken": "text"
}

Create role

post

Create a new IAM role for this organization.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

Body

namestringRequired

Role name.

descriptionstringOptional

Role description.

Responses

201

Created

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

409

The resource already exists

application/json

422

Request validation failed

application/json

post

/organizations/{organizationId}/iam-roles

POST /organizations/{organizationId}/iam-roles HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "name": "text",
  "description": "text",
  "policies": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "managed"
    }
  ],
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "type": "organization",
  "policies": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "definitions": [
        {
          "effect": "allow",
          "resources": [
            "text"
          ],
          "actions": [
            "any"
          ],
          "conditionsAll": [
            {
              "any": {
                "ANY_ADDITIONAL_PROPERTY": {
                  "ANY_ADDITIONAL_PROPERTY": "text"
                }
              }
            }
          ]
        }
      ],
      "rolesDependencyCount": 1,
      "usersDependencyCount": 1,
      "scope": "organization",
      "type": "managed",
      "createdAt": "2025-11-06T01:43:01.195Z",
      "updatedAt": "2025-11-06T01:43:01.195Z",
      "metadata": {
        "clouds": [
          "platform"
        ],
        "apps": [
          "inbox"
        ],
        "groups": [
          "text"
        ]
      }
    }
  ],
  "usersDependencyCount": 1,
  "accessKeysDependencyCount": 1,
  "createdAt": "2025-11-06T01:43:01.195Z",
  "updatedAt": "2025-11-06T01:43:01.195Z",
  "metadata": {
    "clouds": [
      "platform"
    ]
  },
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

Get role

get

Retrieve a single IAM role.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

roleIdstringRequired

ID for an IAM role

Responses

200

application/json

404

Resource not found

application/json

get

/organizations/{organizationId}/iam-roles/{roleId}

GET /organizations/{organizationId}/iam-roles/{roleId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "type": "organization",
  "policies": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "definitions": [
        {
          "effect": "allow",
          "resources": [
            "text"
          ],
          "actions": [
            "any"
          ],
          "conditionsAll": [
            {
              "any": {
                "ANY_ADDITIONAL_PROPERTY": {
                  "ANY_ADDITIONAL_PROPERTY": "text"
                }
              }
            }
          ]
        }
      ],
      "rolesDependencyCount": 1,
      "usersDependencyCount": 1,
      "scope": "organization",
      "type": "managed",
      "createdAt": "2025-11-06T01:43:01.195Z",
      "updatedAt": "2025-11-06T01:43:01.195Z",
      "metadata": {
        "clouds": [
          "platform"
        ],
        "apps": [
          "inbox"
        ],
        "groups": [
          "text"
        ]
      }
    }
  ],
  "usersDependencyCount": 1,
  "accessKeysDependencyCount": 1,
  "createdAt": "2025-11-06T01:43:01.195Z",
  "updatedAt": "2025-11-06T01:43:01.195Z",
  "metadata": {
    "clouds": [
      "platform"
    ]
  },
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

Delete role

delete

Remove an IAM role from the organization.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

roleIdstringRequired

ID for an IAM role

Responses

204

No content

400

Cannot remove role because it's still in use

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

409

The HTTP 409 Conflict response status code indicates a request conflict with current state of the target resource.

application/json

410

Resource not found

application/json

delete

/organizations/{organizationId}/iam-roles/{roleId}

DELETE /organizations/{organizationId}/iam-roles/{roleId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

No content

Update role

patch

Update an IAM role's properties.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

roleIdstringRequired

ID for an IAM role

Body

namestringOptional

Role name.

descriptionstringOptional

Role description.

Responses

200

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

application/json

patch

/organizations/{organizationId}/iam-roles/{roleId}

PATCH /organizations/{organizationId}/iam-roles/{roleId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "name": "text",
  "description": "text",
  "policies": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "managed"
    }
  ],
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "type": "organization",
  "policies": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "definitions": [
        {
          "effect": "allow",
          "resources": [
            "text"
          ],
          "actions": [
            "any"
          ],
          "conditionsAll": [
            {
              "any": {
                "ANY_ADDITIONAL_PROPERTY": {
                  "ANY_ADDITIONAL_PROPERTY": "text"
                }
              }
            }
          ]
        }
      ],
      "rolesDependencyCount": 1,
      "usersDependencyCount": 1,
      "scope": "organization",
      "type": "managed",
      "createdAt": "2025-11-06T01:43:01.195Z",
      "updatedAt": "2025-11-06T01:43:01.195Z",
      "metadata": {
        "clouds": [
          "platform"
        ],
        "apps": [
          "inbox"
        ],
        "groups": [
          "text"
        ]
      }
    }
  ],
  "usersDependencyCount": 1,
  "accessKeysDependencyCount": 1,
  "createdAt": "2025-11-06T01:43:01.195Z",
  "updatedAt": "2025-11-06T01:43:01.195Z",
  "metadata": {
    "clouds": [
      "platform"
    ]
  },
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

Last updated 14 days ago

Was this helpful?