AWS IAM AcquireRole and Role Templates Guide

Quick answer

iam:AcquireRole is the API behind AWS IAM Role Manager’s create-or-reuse workflow. Supply an AWS-managed role-template ARN and its required replacement values. IAM returns a matching role when one exists or creates a new role from the template when the caller is authorized.

The template is a blueprint containing:

• a trust policy defining who can assume the role;
• permissions defining what the role can do;
• an ARN and immutable version;
• optional parameters such as RoleName, AWSServiceName, account IDs, Region, or resource identifiers.

Do not reduce this to “AWS creates a safe role.” The exact version and supplied values determine the output, and some templates are deliberately broad starting points.

Inspect before acquisition

Use GetRoleTemplateVersion with the exact template ARN. AWS says template versions are immutable, but definitions can differ between versions, so record both major and minor version evidence.

Review:

1. trusted service principals and conditions;
2. managed and inline permissions;
3. required and optional parameters;
4. resource placeholders and scope;
5. tagging and permissions-boundary behavior where present;
6. the caller actions required to materialize the role;
7. whether the output is a bounded task role or a broad development role.

The live directory is authority for current templates. As of the source check, PowerUserRoleTemplate:1 is listed for Elastic Beanstalk, EventBridge, Lambda, and Step Functions, while SageMaker Unified Studio and Secrets Manager use service-specific templates and parameters.

AcquireRole create-or-reuse behavior

The request uses a template ARN and replacement values. Conceptually:

template_arn = arn:aws:iam::aws:role-template/iam.amazonaws.com/PowerUserRoleTemplate:1
replacement_values = {
  AWSServiceName: <reviewed service principal>,
  RoleName: <approved role name>
}

This is a planning example, not a copy-paste request. Retrieve the current template and API schema before implementation.

AWS documents two outcomes:

• reuse: a matching role exists, so AcquireRole returns it;
• create: no match exists, so the API builds the trust policy and permissions from the template and parameters.

Reusing can reduce duplicate roles, but “matching” does not establish that every resource should share the same role. Check blast radius, lifecycle coupling, audit ownership, and whether one resource’s future permissions could affect another.

Permission model

AcquireRole does not provide independent authority. AWS evaluates the IAM actions used by the selected outcome:

• reuse requires iam:GetRole;
• template inspection requires iam:GetRoleTemplateVersion;
• creation requires iam:CreateRole;
• managed policies require iam:AttachRolePolicy;
• inline policies require iam:PutRolePolicy;
• a particular template can require additional actions.

Grant these through a narrow identity policy and, when relevant, an organization SCP using iam:RoleTemplateARN. Test a denied template and a denied policy attachment so failure behavior is understood.

Template lifecycle versus role lifecycle

An immutable template version makes the blueprint reconstructable, but the resulting role remains editable IAM state. AWS returns the template reference with role inspection APIs so you can identify provenance.

If an authorized owner changes the role’s policies or trust policy, AWS says Role Manager stops managing that role and it will not pick up future template-version changes. Preserve the change rationale and previous policy for rollback.

Disabling the account setting does not remove created roles. Template retirement, account disablement, role modification, and role deletion are separate lifecycle events.

CloudTrail acceptance record

A create outcome is recorded as an AcquireRole event with the caller, request template, minor version, replacement values, and returned role. Use it to reconcile the service resource with IAM state.

An acceptance record should answer:

• Who requested the role and under which session?
• Which exact template version and parameters were used?
• Was the role created or reused?
• Which resource received it?
• What trust and permissions were actually materialized?
• Who owns review, narrowing, drift, and retirement?

For account-level setup and SCPs, start with the Role Manager guide. For post-creation narrowing, use the least-privilege production guide.

Frequently asked questions

What does the IAM AcquireRole API do?

AcquireRole takes a role-template ARN and required parameter values, then returns a matching existing role or creates a role from the template if the caller has the underlying IAM permissions.

Can AWS change an existing role-template version?

AWS says template versions are immutable. A template update is published as a new version, but definitions can differ across versions.

Should an application call AcquireRole without inspecting the template?

No. Retrieve the exact version with GetRoleTemplateVersion, review its trust policy, permissions, parameters, and required caller actions, then approve the resulting role for the intended account and resource.

Official sources

• AWS IAM: Overview of role templates
• AWS IAM: Manage access to Role Manager
• AWS IAM API: AcquireRole
• AWS IAM API: GetRoleTemplateVersion

Source check: August 19, 2026. Recheck the live template directory, exact version, parameters, API schema, permissions, CloudTrail event, and service-resource attachment before use.