Latest Content

How to Assume a Role

Updated on 01 June, 2026

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.

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 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
  • Terraform

  1. Send a GET request to the List Roles endpoint 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.

  2. Identify the user_id of the user assuming the role. Follow the steps in How to List All Users in an Organization to retrieve user IDs.

  3. Send a POST request to the Create Assumed Role Session endpoint 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.
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 is configured in your Terraform project.

  2. 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]
}

  3. Apply the configuration.

    console 
    $ terraform apply

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

Comments