Organization roles

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

List roles

List the IAM roles that are defined for this organization.

GET/organizations/{organizationId}/iam-roles

Authorization

Path parameters

organizationId*string

The organization ID

Query parameters

Response

Body

results*array of Role

List of roles.

nextPageTokenstring

The token to fetch the next page of results. If empty, there are no more results to fetch.

Request

const response = await fetch('/organizations/{organizationId}/iam-roles', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "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": [
                {}
              ]
            }
          ],
          "scope": "organization",
          "type": "managed",
          "createdAt": "2024-05-08T20:00:28.112Z",
          "updatedAt": "2024-05-08T20:00:28.112Z"
        }
      ],
      "createdAt": "2024-05-08T20:00:28.112Z",
      "updatedAt": "2024-05-08T20:00:28.112Z"
    }
  ],
  "nextPageToken": "text"
}

Create role

Create a new IAM role for this organization.

POST/organizations/{organizationId}/iam-roles

Authorization

Path parameters

organizationId*string

The organization ID

Body

name*iam_role_properties-name (string)

Role name.

descriptiondescription (string)

Role description.

policies*array of PolicyRef

IAM Policies this role contains.

Response

Created

Body

id*string (uuid)

ID of the role.

organizationIdstring (uuid)

ID of the organization to which this role belongs.

name*string

Role name.

descriptionstring

Role description.

type*enum

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

organizationmanaged

policies*array of one of

IAM Policies this role contains.

usersDependencyCount*integer

The number of users this role is assigned to.

accessKeysDependencyCount*integer

The number of access keys this role is assigned to.

createdAt*string (date-time)

When this role was created.

updatedAt*string (date-time)

When this role was last updated.

Request

const response = await fetch('/organizations/{organizationId}/iam-roles', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "policies": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "managed"
        }
      ]
    }),
});
const data = await response.json();

Response

{
  "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": [
            {}
          ]
        }
      ],
      "scope": "organization",
      "type": "managed",
      "createdAt": "2024-05-08T20:00:28.112Z",
      "updatedAt": "2024-05-08T20:00:28.112Z"
    }
  ],
  "createdAt": "2024-05-08T20:00:28.112Z",
  "updatedAt": "2024-05-08T20:00:28.112Z"
}

Get role

Retrieve a single IAM role.

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

Authorization

Path parameters

organizationId*string

The organization ID

roleId*string

ID for an IAM role

Response

Body

id*string (uuid)

ID of the role.

organizationIdstring (uuid)

ID of the organization to which this role belongs.

name*string

Role name.

descriptionstring

Role description.

type*enum

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

organizationmanaged

policies*array of one of

IAM Policies this role contains.

usersDependencyCount*integer

The number of users this role is assigned to.

accessKeysDependencyCount*integer

The number of access keys this role is assigned to.

createdAt*string (date-time)

When this role was created.

updatedAt*string (date-time)

When this role was last updated.

Request

const response = await fetch('/organizations/{organizationId}/iam-roles/{roleId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "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": [
            {}
          ]
        }
      ],
      "scope": "organization",
      "type": "managed",
      "createdAt": "2024-05-08T20:00:28.112Z",
      "updatedAt": "2024-05-08T20:00:28.112Z"
    }
  ],
  "createdAt": "2024-05-08T20:00:28.112Z",
  "updatedAt": "2024-05-08T20:00:28.112Z"
}

Delete role

Remove an IAM role from the organization.

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

Authorization

Path parameters

organizationId*string

The organization ID

roleId*string

ID for an IAM role

Response

Request

const response = await fetch('/organizations/{organizationId}/iam-roles/{roleId}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Update role

Update an IAM role's properties.

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

Authorization

Path parameters

organizationId*string

The organization ID

roleId*string

ID for an IAM role

Body

nameiam_role_properties-name (string)

Role name.

descriptiondescription (string)

Role description.

policiesarray of PolicyRef

IAM Policies this role contains.

Response

Body

id*string (uuid)

ID of the role.

organizationIdstring (uuid)

ID of the organization to which this role belongs.

name*string

Role name.

descriptionstring

Role description.

type*enum

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

organizationmanaged

policies*array of one of

IAM Policies this role contains.

usersDependencyCount*integer

The number of users this role is assigned to.

accessKeysDependencyCount*integer

The number of access keys this role is assigned to.

createdAt*string (date-time)

When this role was created.

updatedAt*string (date-time)

When this role was last updated.

Request

const response = await fetch('/organizations/{organizationId}/iam-roles/{roleId}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "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": [
            {}
          ]
        }
      ],
      "scope": "organization",
      "type": "managed",
      "createdAt": "2024-05-08T20:00:28.112Z",
      "updatedAt": "2024-05-08T20:00:28.112Z"
    }
  ],
  "createdAt": "2024-05-08T20:00:28.112Z",
  "updatedAt": "2024-05-08T20:00:28.112Z"
}

Last updated 1 year ago

const response = await fetch('/organizations/{organizationId}/iam-roles', { method: 'POST', headers: { "Authorization": "Bearer jwt", "Content-Type": "application/json" }, body: JSON.stringify({ "name": "text", "policies": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "managed" } ] }), }); const data = await response.json();

{ "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": [ {} ] } ], "scope": "organization", "type": "managed", "createdAt": "2024-05-08T20:00:28.112Z", "updatedAt": "2024-05-08T20:00:28.112Z" } ], "createdAt": "2024-05-08T20:00:28.112Z", "updatedAt": "2024-05-08T20:00:28.112Z" }

const response = await fetch('/organizations/{organizationId}/iam-roles/{roleId}', { method: 'PATCH', headers: { "Authorization": "Bearer jwt", "Content-Type": "application/json" }, body: JSON.stringify({}), }); const data = await response.json();