Latest Content

How to Assume a Role Using AWS Security Token Service (STS) Compatibility

Updated on 08 April, 2026

Assume a Vultr IAM role using the AWS STS-compatible endpoint. Use existing AWS tooling and SDKs to obtain temporary credentials for Vultr cloud resources.

Vultr provides an AWS STS-compatible endpoint that allows you to assume a role using the same request format as AWS Security Token Service. This is useful for integrating with tools and SDKs built for AWS STS, enabling a seamless migration path from AWS to Vultr.

The endpoint supports two actions:

  • AssumeRole: For role assumption where the caller authenticates with a Vultr API key. The role must have a trust relationship granting access to the API user.
  • AssumeRoleWithWebIdentity: For federated role assumption using a JWT token from an external OIDC issuer (such as Okta, Google, or Azure AD). The role must have a trust relationship pointing to the OIDC issuer.
Note
This endpoint uses application/x-www-form-urlencoded content type and returns an XML response, matching the AWS STS API format. The RoleArn parameter follows the AWS ARN format: arn:aws:iam::ORGANIZATION-ID:role/ROLE-ID.

This guide explains how to assume a role using the AWS STS compatibility endpoint via 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. Send a POST request to the Assume Role AWS STS endpoint to assume the role.

    To assume a role with a Vultr API key, use the AssumeRole action. Replace ORGANIZATION-ID with your organization id, ROLE-ID with the assumable role id, and SESSION-NAME with a descriptive name for the session.

    console 
    $ curl "https://api.vultr.com/v2/assumed-roles/compatibility/aws/sts" \
    -X POST \
    -H "Authorization: Bearer ${VULTR_API_KEY}" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Accept: application/xml" \
    --data "Action=AssumeRole&RoleArn=arn:aws:iam::ORGANIZATION-ID:role/ROLE-ID&RoleSessionName=SESSION-NAME"

    To assume a role using a JWT token from an external OIDC issuer, use the AssumeRoleWithWebIdentity action. Replace OIDC-JWT with the JWT token issued by the trusted OIDC provider.

    console 
    $ curl "https://api.vultr.com/v2/assumed-roles/compatibility/aws/sts" \
    -X POST \
    -H "Authorization: Bearer OIDC-JWT" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Accept: application/xml" \
    --data "Action=AssumeRoleWithWebIdentity&RoleArn=arn:aws:iam::ORGANIZATION-ID:role/ROLE-ID&RoleSessionName=SESSION-NAME&WebIdentityToken=OIDC-JWT"

    A successful response returns an XML body in the AWS STS format containing the session credentials.

Comments