---
title: "Role"
description: "IAM roles lets you define logical sets of policies to grant to users and API keys."
url: https://community.exoscale.com/reference/api/iam/role/
section: reference
last_updated: 2026-10-14
---
> For AI agents: the documentation index is at https://community.exoscale.com/llms.txt. Every page is available as markdown at `<page URL>index.md` or with `Accept: text/markdown`.

# Role

IAM roles lets you define logical sets of policies to grant to users and API keys.

[Read more](https://community.exoscale.com/product/security/iam/how-to/role-mgmt/index.md)

## <span data-label="POST" class="pill-POST"></span>create-iam-role

Create IAM Role

```
POST /iam-role
```

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | **yes** | IAM Role name<br/><br/>Min length: `1`. Max length: `191`. |
| `assume-role-policy` | [Assume Role Policy](https://community.exoscale.com/reference/api/_schemas/iam-assume-role-policy/index.md) | no | IAM Assume role policy |
| `description` | string | no | IAM Role description<br/><br/>Min length: `1`. Max length: `255`. |
| `editable` | boolean | no | Sets if the IAM Role Policy is editable or not (default: true). This setting cannot be changed after creation |
| `labels` | object | no | IAM Role labels |
| `max-session-ttl` | integer | no | Maximum TTL requester is allowed to ask for when assuming a role<br/><br/>Min: `0`. |
| `permissions` | array[string] | no | IAM Role permissions |
| `policy` | [Policy](https://community.exoscale.com/reference/api/_schemas/iam-policy/index.md) | no | IAM Role policy |

<details>
<summary>Example</summary>

```json
{
  "assume-role-policy": {
    "rules": [
      {
        "action": "allow",
        "expression": "string",
        "resources": [
          "string"
        ]
      }
    ]
  },
  "description": "string",
  "editable": true,
  "labels": {},
  "max-session-ttl": 1,
  "name": "string",
  "permissions": [
    "bypass-governance-retention"
  ],
  "policy": {
    "default-service-strategy": "allow",
    "services": {}
  }
}
```
</details>


### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `id` | string | Operation ID<br/><br/>Must be a valid UUID. |
| `message` | string | Operation message |
| `reason` | string | Operation failure reason<br/><br/>Allowed values: `incorrect`, `unknown`, `unavailable`, `forbidden`, `busy`, `fault`, `partial`, `not-found`, `interrupted`, `unsupported`, `conflict`. |
| `reference` | [Reference](https://community.exoscale.com/reference/api/_schemas/operation/index.md#reference) | Related resource reference |
| `state` | string | Operation status<br/><br/>Allowed values: `failure`, `pending`, `success`, `timeout`. |

<details>
<summary>Example output</summary>

```json
{
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "message": "string",
  "reason": "incorrect",
  "reference": {
    "command": "string",
    "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
    "link": "string"
  },
  "state": "failure"
}
```
</details>


SDK reference for `create-iam-role`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.CreateIAMRole) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.create_iam_role) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#createIamRole(com.exoscale.sdk.model.CreateIamRoleRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api create-iam-role`

## <span data-label="GET" class="pill-GET"></span>get-iam-role

Retrieve IAM Role

```
GET /iam-role/{id}
```

### Path parameters

| Name | In | Description |
| --- | --- | --- |
| `id` | `path` | Must be a valid UUID. |

### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `assume-role-policy` | [Assume Role Policy](https://community.exoscale.com/reference/api/_schemas/iam-assume-role-policy/index.md) | IAM Assume Role Policy |
| `description` | string | IAM Role description<br/><br/>Min length: `1`. Max length: `255`. |
| `editable` | boolean | IAM Role mutability |
| `id` | string | IAM Role ID<br/><br/>Must be a valid UUID. |
| `labels` | object | IAM Role Labels |
| `max-session-ttl` | integer | Maximum TTL requester is allowed to ask for when assuming a role<br/><br/>Min: `0`. |
| `name` | string | IAM Role name<br/><br/>Min length: `1`. Max length: `255`. |
| `permissions` | array[string] | IAM Role permissions |
| `policy` | [Policy](https://community.exoscale.com/reference/api/_schemas/iam-policy/index.md) | IAM Role Policy |

<details>
<summary>Example output</summary>

```json
{
  "assume-role-policy": {
    "rules": [
      {
        "action": "allow",
        "expression": "string",
        "resources": [
          "string"
        ]
      }
    ]
  },
  "description": "string",
  "editable": true,
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "labels": {},
  "max-session-ttl": 1,
  "name": "string",
  "permissions": [
    "bypass-governance-retention"
  ],
  "policy": {
    "default-service-strategy": "allow",
    "services": {}
  }
}
```
</details>


SDK reference for `get-iam-role`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.GetIAMRole) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.get_iam_role) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#getIamRole(java.util.UUID))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api get-iam-role`

## <span data-label="PUT" class="pill-PUT"></span>update-iam-role

Update IAM Role

```
PUT /iam-role/{id}
```

### Path parameters

| Name | In | Description |
| --- | --- | --- |
| `id` | `path` | Must be a valid UUID. |

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `assume-role-policy` | [Assume Role Policy](https://community.exoscale.com/reference/api/_schemas/iam-assume-role-policy/index.md) | no | IAM Assume role policy |
| `description` | string | no | IAM Role description<br/><br/>Min length: `1`. Max length: `255`. |
| `labels` | object | no | IAM Role labels |
| `max-session-ttl` | integer | no | Maximum TTL requester is allowed to ask for when assuming a role<br/><br/>Min: `0`. |
| `permissions` | array[string] | no | IAM Role permissions |

<details>
<summary>Example</summary>

```json
{
  "assume-role-policy": {
    "rules": [
      {
        "action": "allow",
        "expression": "string",
        "resources": [
          "string"
        ]
      }
    ]
  },
  "description": "string",
  "labels": {},
  "max-session-ttl": 1,
  "permissions": [
    "bypass-governance-retention"
  ]
}
```
</details>


### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `id` | string | Operation ID<br/><br/>Must be a valid UUID. |
| `message` | string | Operation message |
| `reason` | string | Operation failure reason<br/><br/>Allowed values: `incorrect`, `unknown`, `unavailable`, `forbidden`, `busy`, `fault`, `partial`, `not-found`, `interrupted`, `unsupported`, `conflict`. |
| `reference` | [Reference](https://community.exoscale.com/reference/api/_schemas/operation/index.md#reference) | Related resource reference |
| `state` | string | Operation status<br/><br/>Allowed values: `failure`, `pending`, `success`, `timeout`. |

<details>
<summary>Example output</summary>

```json
{
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "message": "string",
  "reason": "incorrect",
  "reference": {
    "command": "string",
    "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
    "link": "string"
  },
  "state": "failure"
}
```
</details>


SDK reference for `update-iam-role`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.UpdateIAMRole) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.update_iam_role) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#updateIamRole(java.util.UUID,com.exoscale.sdk.model.UpdateIamRoleRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api update-iam-role`

## <span data-label="DELETE" class="pill-DELETE"></span>delete-iam-role

Delete IAM Role

```
DELETE /iam-role/{id}
```

### Path parameters

| Name | In | Description |
| --- | --- | --- |
| `id` | `path` | Must be a valid UUID. |

### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `id` | string | Operation ID<br/><br/>Must be a valid UUID. |
| `message` | string | Operation message |
| `reason` | string | Operation failure reason<br/><br/>Allowed values: `incorrect`, `unknown`, `unavailable`, `forbidden`, `busy`, `fault`, `partial`, `not-found`, `interrupted`, `unsupported`, `conflict`. |
| `reference` | [Reference](https://community.exoscale.com/reference/api/_schemas/operation/index.md#reference) | Related resource reference |
| `state` | string | Operation status<br/><br/>Allowed values: `failure`, `pending`, `success`, `timeout`. |

<details>
<summary>Example output</summary>

```json
{
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "message": "string",
  "reason": "incorrect",
  "reference": {
    "command": "string",
    "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
    "link": "string"
  },
  "state": "failure"
}
```
</details>


SDK reference for `delete-iam-role`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.DeleteIAMRole) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.delete_iam_role) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#deleteIamRole(java.util.UUID))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api delete-iam-role`


---

## Other Operations

## <span data-label="POST" class="pill-POST"></span>assume-iam-role

[BETA] Request generation of key/secret that allow caller to assume target role

```
POST /iam-role/{id}/assume
```

[BETA] Request generation of key/secret that allow caller to assume target role

### Path parameters

| Name | In | Description |
| --- | --- | --- |
| `id` | `path` | Must be a valid UUID. |

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `ttl` | integer | **yes** | TTL in seconds for the generated access key (cannot exceed the max TTL defined in the targeted assume role)<br/><br/>Min: `0`. |
| `org-id` | string | no | Organization ID target of the assume role action<br/><br/>Must be a valid UUID. |

<details>
<summary>Example</summary>

```json
{
  "org-id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "ttl": 1
}
```
</details>


### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `expires-at` | string |  |
| `key` | string |  |
| `name` | string |  |
| `org-id` | string |  |
| `role-id` | string |  |
| `secret` | string |  |

<details>
<summary>Example output</summary>

```json
{
  "expires-at": "string",
  "key": "string",
  "name": "string",
  "org-id": "string",
  "role-id": "string",
  "secret": "string"
}
```
</details>


SDK reference for `assume-iam-role`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.AssumeIAMRole) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.assume_iam_role) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#assumeIamRole(java.util.UUID,com.exoscale.sdk.model.AssumeIamRoleRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api assume-iam-role`

## <span data-label="PUT" class="pill-PUT"></span>update-iam-role-policy

Update IAM Role Policy

```
PUT /iam-role/{id}:policy
```

### Path parameters

| Name | In | Description |
| --- | --- | --- |
| `id` | `path` | Must be a valid UUID. |

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `default-service-strategy` | string | **yes** | IAM default service strategy<br/><br/>Allowed values: `allow`, `deny`. |
| `services` | object | **yes** | IAM services |

<details>
<summary>Example</summary>

```json
{
  "default-service-strategy": "allow",
  "services": {}
}
```
</details>


### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `id` | string | Operation ID<br/><br/>Must be a valid UUID. |
| `message` | string | Operation message |
| `reason` | string | Operation failure reason<br/><br/>Allowed values: `incorrect`, `unknown`, `unavailable`, `forbidden`, `busy`, `fault`, `partial`, `not-found`, `interrupted`, `unsupported`, `conflict`. |
| `reference` | [Reference](https://community.exoscale.com/reference/api/_schemas/operation/index.md#reference) | Related resource reference |
| `state` | string | Operation status<br/><br/>Allowed values: `failure`, `pending`, `success`, `timeout`. |

<details>
<summary>Example output</summary>

```json
{
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "message": "string",
  "reason": "incorrect",
  "reference": {
    "command": "string",
    "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
    "link": "string"
  },
  "state": "failure"
}
```
</details>


SDK reference for `update-iam-role-policy`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.UpdateIAMRolePolicy) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.update_iam_role_policy) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#updateIamRolePolicy(java.util.UUID,com.exoscale.sdk.model.UpdateIamRolePolicyRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api update-iam-role-policy`

## <span data-label="GET" class="pill-GET"></span>list-iam-roles

List IAM Roles

```
GET /iam-role
```

### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `iam-roles` | array of [IAM Role](https://community.exoscale.com/reference/api/_schemas/iam-role/index.md) |  |

<details>
<summary>Example output</summary>

```json
{
  "iam-roles": [
    {
      "assume-role-policy": {
        "rules": [
          {
            "action": null,
            "expression": null,
            "resources": null
          }
        ]
      },
      "description": "string",
      "editable": true,
      "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
      "labels": {},
      "max-session-ttl": 1,
      "name": "string",
      "permissions": [
        "bypass-governance-retention"
      ],
      "policy": {
        "default-service-strategy": "allow",
        "services": {}
      }
    }
  ]
}
```
</details>


SDK reference for `list-iam-roles`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.ListIAMRoles) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.list_iam_roles) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#listIamRoles())

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api list-iam-roles`

## <span data-label="GET" class="pill-GET"></span>list-iam-system-roles

List IAM System Roles

```
GET /iam-system-role
```

### Responses

Status: `200` - 200

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `iam-system-roles` | array of [IAM System Role](https://community.exoscale.com/reference/api/_schemas/iam-system-role/index.md) |  |

<details>
<summary>Example output</summary>

```json
{
  "iam-system-roles": [
    {
      "assume-role-policy": {
        "rules": [
          {
            "action": null,
            "expression": null,
            "resources": null
          }
        ]
      },
      "description": "string",
      "editable": true,
      "id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
      "labels": {},
      "max-session-ttl": 1,
      "name": "string",
      "permissions": [
        "bypass-governance-retention"
      ],
      "policy": {
        "default-service-strategy": "allow",
        "services": {}
      }
    }
  ]
}
```
</details>


SDK reference for `list-iam-system-roles`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.ListIAMSystemRoles) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.list_iam_system_roles) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#listIamSystemRoles())

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api list-iam-system-roles`


