Latest Content

How to Assume a Role

Updated on 08 April, 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.

This guide explains how to assume a role using the Vultr API.

  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.

Comments