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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

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

OK

application/json

401

unauthorized request

application/json

404

Resource not found

application/json

get

/organizations/{organizationId}/iam-roles

HTTPcURLJavaScriptPython

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": "2026-02-25T19:05:39.317Z",
          "updatedAt": "2026-02-25T19:05:39.317Z",
          "metadata": {
            "clouds": [
              "platform"
            ],
            "apps": [
              "inbox"
            ],
            "groups": [
              "text"
            ]
          }
        }
      ],
      "usersDependencyCount": 1,
      "accessKeysDependencyCount": 1,
      "createdAt": "2026-02-25T19:05:39.317Z",
      "updatedAt": "2026-02-25T19:05:39.317Z",
      "metadata": {
        "clouds": [
          "platform"
        ]
      },
      "actions": [
        {
          "name": "text",
          "type": "text"
        }
      ]
    }
  ],
  "nextPageToken": "text"
}

Create role

post

Create a new IAM role for this organization.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

Body

application/json

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

HTTPcURLJavaScriptPython

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": "2026-02-25T19:05:39.317Z",
      "updatedAt": "2026-02-25T19:05:39.317Z",
      "metadata": {
        "clouds": [
          "platform"
        ],
        "apps": [
          "inbox"
        ],
        "groups": [
          "text"
        ]
      }
    }
  ],
  "usersDependencyCount": 1,
  "accessKeysDependencyCount": 1,
  "createdAt": "2026-02-25T19:05:39.317Z",
  "updatedAt": "2026-02-25T19:05:39.317Z",
  "metadata": {
    "clouds": [
      "platform"
    ]
  },
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

Get role

get

Retrieve a single IAM role.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

roleIdstringRequired

ID for an IAM role

Responses

200

OK

application/json

idstring · uuidRequired

ID of the role.

organizationIdstring · uuidOptional

ID of the organization to which this role belongs.

namestringRequired

Role name.

descriptionstringOptional

Role description.

typestring · enumRequired

Whether this role is managed by MessageBird or by the organization.

Possible values:

usersDependencyCountintegerRequired

The number of users this role is assigned to.

accessKeysDependencyCountintegerRequired

The number of access keys this role is assigned to.

createdAtstring · date-timeRequired

When this role was created.

updatedAtstring · date-timeRequired

When this role was last updated.

404

Resource not found

application/json

get

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

HTTPcURLJavaScriptPython

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": "2026-02-25T19:05:39.317Z",
      "updatedAt": "2026-02-25T19:05:39.317Z",
      "metadata": {
        "clouds": [
          "platform"
        ],
        "apps": [
          "inbox"
        ],
        "groups": [
          "text"
        ]
      }
    }
  ],
  "usersDependencyCount": 1,
  "accessKeysDependencyCount": 1,
  "createdAt": "2026-02-25T19:05:39.317Z",
  "updatedAt": "2026-02-25T19:05:39.317Z",
  "metadata": {
    "clouds": [
      "platform"
    ]
  },
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

Delete role

delete

Remove an IAM role from the organization.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

roleIdstringRequired

ID for an IAM role

Responses

204

OK

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}

HTTPcURLJavaScriptPython

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

roleIdstringRequired

ID for an IAM role

Body

application/json

namestringOptional

Role name.

descriptionstringOptional

Role description.

Responses

200

OK

application/json

idstring · uuidRequired

ID of the role.

organizationIdstring · uuidOptional

ID of the organization to which this role belongs.

namestringRequired

Role name.

descriptionstringOptional

Role description.

typestring · enumRequired

Whether this role is managed by MessageBird or by the organization.

Possible values:

usersDependencyCountintegerRequired

The number of users this role is assigned to.

accessKeysDependencyCountintegerRequired

The number of access keys this role is assigned to.

createdAtstring · date-timeRequired

When this role was created.

updatedAtstring · date-timeRequired

When this role was last updated.

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

application/json

patch

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

HTTPcURLJavaScriptPython

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": "2026-02-25T19:05:39.317Z",
      "updatedAt": "2026-02-25T19:05:39.317Z",
      "metadata": {
        "clouds": [
          "platform"
        ],
        "apps": [
          "inbox"
        ],
        "groups": [
          "text"
        ]
      }
    }
  ],
  "usersDependencyCount": 1,
  "accessKeysDependencyCount": 1,
  "createdAt": "2026-02-25T19:05:39.317Z",
  "updatedAt": "2026-02-25T19:05:39.317Z",
  "metadata": {
    "clouds": [
      "platform"
    ]
  },
  "actions": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}