---
title: How to Assume a Role
url: https://docs.vultr.com/platform/iam/roles/assumed-roles/how-to-assume-a-role
description: Assume an IAM role on Vultr to gain temporary elevated permissions. Create a time-bound session with the role's policies applied to your API access credentials.
publish_date: 2026-03-24T19:52:30.347831Z
last_updated: 2026-06-01T20:43:32.995000Z
---

Assuming a role creates a temporary session that grants the permissions defined by the role's policies. This is used with assumable roles that have a trust relationship configured. The session is time-bound and expires after the specified duration or when the role's `max_session_duration` is reached.

> [!NOTE]
> Before assuming a role, you must have a role trust configured that grants your user access to the assumable role. See [**How to Create a Role Trust**](https://docs.vultr.com/platform/iam/roles/role-trusts/how-to-create-a-role-trust) for details. The user assuming the role must also have a policy attached with the `iam.role.AssumeRole`, `iam.role.Read`, and `iam.assumedrole.Read` actions.

Follow this guide to assume a role using the Vultr API or Terraform.

=== "Vultr API"

    1. Send a `GET` request to the [**List Roles** endpoint](https://www.vultr.com/api/#tag/iam/operation/list-iam-roles) to retrieve all roles in your organization.

        ```console
        $ curl "https://api.vultr.com/v2/roles" \
            -X GET \
            -H "Authorization: Bearer ${VULTR_API_KEY}"
        ```

        Note the `id` of the assumable role you want to assume.

    1. Identify the `user_id` of the user assuming the role. Follow the steps in [How to List All Users in an Organization](https://docs.vultr.com/platform/iam/organizations/how-to-list-all-users-in-an-organization) to retrieve user IDs.

    1. Send a `POST` request to the [**Create Assumed Role Session** endpoint](https://www.vultr.com/api/#tag/iam/operation/iam-assume-role) to assume the role.

        ```console
        $ curl "https://api.vultr.com/v2/assumed-roles/assume" \
            -X POST \
            -H "Authorization: Bearer ${VULTR_API_KEY}" \
            -H "Content-Type: application/json" \
            -d '{
                "user_id": "USER-ID",
                "role_id": "ROLE-ID",
                "session_name": "SESSION-NAME",
                "auth_method": "api_key",
                "duration": 3600
            }'
        ```

        In the above request:

        * `user_id`: The user assuming the role. Use `oidc_issuer_id` instead for OIDC-authenticated users.
        * `auth_method`: Must be one of `api_key`, `jwt`, or `oidc`.
        * `duration`: Session length in seconds.

        A successful request returns an HTTP `201 Created` response.

        > [!NOTE]
        > The `session_token` grants the user permission to make API calls based on the policies attached to the assumed role. Pass it as the `Authorization: Bearer` token in subsequent requests. The session expires after the specified duration.

=== "Terraform"

    > [!NOTE]
    > If the role trust and the role session are being created in the same `terraform apply`, you must add `depends_on` pointing to the trust resource. Without it, Terraform creates both in parallel and the session request reaches the API before the trust is established, returning a `403` error.

    1. Ensure the [Vultr Terraform provider](https://registry.terraform.io/providers/vultr/vultr/latest/docs) is configured in your Terraform project.

    1. Define the role session resource. Replace `SESSION-NAME` with a name for the session.

        ```hcl
        resource "vultr_organization_role_session" "my_session" {
          user_id      = vultr_user.new_user.id
          role_id      = vultr_organization_role.my_role.id
          session_name = "SESSION-NAME"
          duration     = 3600
          ip_address   = "10.0.0.1"

          depends_on = [vultr_organization_role_trust.my_role_trust]
        }
        ```

    1. Apply the configuration.

        ```console
        $ terraform apply
        ```

        Verify that the output shows `vultr_organization_role_session.my_session: Creation complete`.