How to Assume a Role with an Instance Identity Token

A Vultr Cloud Compute instance or Bare Metal server can assume an IAM role using its own identity token in place of a user's credentials. The identity token itself authenticates the request, so the assume-role call needs no user_id or oidc_issuer_id.

Follow this guide to assume a role from within an instance or bare metal server using the Vultr API.

1. Obtain an identity token from the server's metadata service.

2. Send a POST request to the Create Assumed Role Session endpoint, passing the identity token as the Authorization header instead of a Vultr API key. Replace IDENTITY-TOKEN with the token from the previous step, ROLE-ID with the assumable role id, and SESSION-NAME with a name for the session.

   CONSOLE

   Copy

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

   Explain Code

   Powered by Vultr AgentBeta

   A successful request returns an HTTP 201 Created response with a session_token prefixed ars-. Both user_id and oidc_issuer_id return empty in the response, since the session is tied to the entity's trust rather than a platform user.

   Note

   Pass session_token as the Authorization: Bearer token in subsequent requests. The session expires after the specified duration.