# IAM temporary delegation for AWS Partners
## Overview
IAM temporary delegation enables AWS customers to seamlessly onboard and/or integrate AWS Partner products into their AWS environment through interactive, guided workflows. Customers can grant AWS Partners limited, temporary access to configure required AWS services, reducing onboarding friction and accelerating time to value.
IAM temporary delegation enables partners to:
+ Streamline customer onboarding with automated resource provisioning
+ Reduce integration complexity by eliminating manual configuration steps
+ Build trust through transparent, customer-approved permissions
+ Enable ongoing operations with long-term access patterns using permission boundaries
## How it works
1. *Partner creates a delegation request* - Partners create a request specifying what permissions they need and for how long
1. *Customer reviews in AWS Console* - Customer sees exactly what permissions partner is requesting and why
1. *Customer approves* - Customer approves the request and releases an exchange token. The token is sent to partner on this specified SNS topic.
1. *Partner receives temporary credentials* - Partners exchange the token for temporary AWS credentials
1. *Partner configures resources* - Partners use the credentials to set up required resources in the customer's account
## Partner qualification
To qualify for temporary delegation integration, a partner must meet the following requirements:
+ *ISV Accelerate participation* – You must be enrolled in the [ISV Accelerate (ISVA)](https://aws.amazon.com/partners/programs/isv-accelerate/) program.
+ *AWS Marketplace listing* – Your product must be listed in the AWS Marketplace with a "Deployed on AWS" badge.
## Onboarding process
Complete the following steps to integrate temporary delegation into your product:
1. *Step 1: Review requirements*
Review this documentation to understand the qualification requirements and complete the partner questionnaire below.
1. *Step 2: Submit your onboarding request*
Send an email to aws-iam-partner-onboarding@amazon.com or contact your AWS representative. Include your completed partner questionnaire with all required fields from the table below.
1. *Step 3: AWS validation and review*
AWS will:
+ Validate that you meet the qualification criteria
+ Review your policy templates and permission boundaries
+ Provide feedback on your submitted artifacts
1. *Step 4: Refine your policies*
Respond to AWS feedback and submit updated policy templates or permission boundaries as needed.
1. *Step 5: Complete registration*
Once approved, AWS will:
+ Enable API access for your specified accounts
+ Share ARNs for your policy template and permissions boundary (if applicable)
You will receive confirmation when onboarding is complete. You can then access temporary delegation APIs, CreateDelegationRequest and GetDelegatedAccessToken from your registered accounts and begin integrating delegation request workflows into your product.
## Partner questionnaire
The following table lists the information required for partner onboarding:
| Information | Description | Required |
| --- | --- | --- |
| Partner Central AccountID | Account ID of your registered AWS account on [AWS Partner Central](https://partnercentral.awspartner.com/partnercentral2/s/login). | Yes |
| PartnerId | Partner ID provided by [AWS Partner Central](https://partnercentral.awspartner.com/partnercentral2/s/login). | No |
| AWS Marketplace Product Id | Product ID for your product provided by [AWS Partner Central](https://partnercentral.awspartner.com/partnercentral2/s/login). | Yes |
| AWS accountIDs | The list of your AWS Account IDs that you want to use to call temporary delegation APIs. This should include both your production and non-production/test accounts. | Yes |
| Partner name | This name is displayed to customers in the AWS Management Console when they review your temporary delegation request. | Yes |
| Contact email(s) | One or more email addresses that we can use to contact you about your integration. | Yes |
| Requestor Domain | Your domain (for example, www.example.com) | Yes |
| Integration description | Brief description of the use case that you want to address using this feature. You can include reference links to your documentation or other public material. | Yes |
| Architecture diagram | Architecture diagram illustrating your integration use case(s). | No |
| Policy template | You must register at least one policy template for this feature. The policy template defines the temporary permissions you want to request in customers' AWS accounts. For more information, see Policy template section. | Yes |
| Policy template name | Name of the policy template you want to register. | Yes |
| Permissions Boundary | If you want to create IAM roles in customers' accounts using temporary permissions, you must register a permission boundary with IAM. Permission boundaries will be attached to the IAM roles that you create to limit the maximum permissions on the role. You can use selected AWS managed policies as a permission boundary or register a new custom permission boundary (JSON). For more information, see Permissions Boundary section. | No |
| Permission Boundary Name | The name of your permission boundary. The format is: arn:aws:iam::partner:policy/permission\$1boundary//\$1 The policy name must include the creation date as a suffix. The name cannot be updated once the permission boundary is created. If you are using an existing AWS managed policy, provide the managed policy ARN instead. | No |
| Permission Boundary Description | Description for the permission boundary. This description cannot be updated once the permission boundary is created. | No |
# Understanding your integration
After completing the onboarding process, you can build your integration with IAM temporary delegation. A complete integration typically involves three main categories of work:
## 1. User Experience and Workflow Design
Build a front-end experience in the partner application that guides customers through the temporary delegation workflow. Partner application should:
+ Present a clear onboarding or configuration flow where customers can grant temporary access. Label this action clearly, such as "Deploy with IAM temporary delegation".
+ Redirect customers to the AWS Management Console to review and approve the delegation request using the console link returned by the CreateDelegationRequest API
+ Provide appropriate messaging about what permissions are being requested and why. Customers can see this message on the delegation request details page.
+ Handle the customer's return to your application after they complete the approval in AWS.
## 2. API Integration
Use IAM temporary delegation APIs to send and manage delegation requests. Once your AWS accounts are registered, you can access the following APIs:
+ *IAM CreateDelegationRequest* – Creates a delegation request for a customer's AWS account. This API returns a console link that you redirect customers to for reviewing and approving the request.
+ *AWS STS GetDelegatedAccessToken* – Retrieves temporary AWS credentials after a customer approves your delegation request. Use these credentials to perform actions in the customer's account.
Your integration should handle the complete lifecycle of delegation requests, including creating requests, monitoring their status, and retrieving temporary credentials when approved.
## 3. Resource Configuration and Orchestration
Once you obtain temporary credentials, orchestrate the necessary workflows to configure resources in the customer's AWS account. This may include:
+ Calling AWS service APIs directly to create and configure resources
+ Deploying infrastructure using AWS CloudFormation templates
+ Creating IAM roles for ongoing access (requires using permission boundaries)
Your orchestration logic should be idempotent and handle failures gracefully, as customers may need to retry or modify their delegation approvals.
# Understanding permissions
As part of the feature onboarding process, you will need to register policies with IAM that define the permissions you want to request in customers' AWS accounts. The registration process provides a more consistent experience for customers and helps avoid common pitfalls in policy authoring.
During registration, AWS evaluates your policies against a set of validations. These validations are intended to standardize policy formatting and structure, and provide basic protections against known anti-patterns. The validations also reduce the risk of privilege escalations, unintended cross-account access, and broad access to high-value resources in customer accounts.
## Permission Types
AWS will consider two categories of permissions: temporary and long-term.
### Temporary Permissions
Temporary permissions limit the permissions assigned to any temporary delegated access sessions. Temporary permissions are described in policy templates that are applied to the delegated session. The templates support parameters that you supply when you create a delegation request. These parameter values are then bound to the session. The temporary permissions work in the same way as the session policies available in AWS STS today: the policies limit the capability of the underlying user, but do not grant any additional access. For more information, see the AWS STS documentation on session policies.
### Long-Term Permissions
Long-term permissions limit the permissions of any roles that are created or managed via temporary access. Long-term permissions are implemented as IAM permissions boundaries. You may submit one or more permission boundaries to AWS as part of onboarding. Once approved, AWS will share a policy ARN with you that you can reference in your policies.
These boundary policies have two noteworthy features. First, they are immutable. If you want to update permissions, you can register a new permissions boundary. You can then attach the new permissions boundary to your customers' roles by sending a new delegation request. Second, the policies are not templated. Since the same boundary policy is globally shared, they cannot be altered on a per-customer basis.
**Important**
Permission boundaries have a maximum size limit of 6,144 characters.
**Note**
If you would like to update a permission boundary or policy template, contact IAM at aws-iam-partner-onboarding@amazon.com. Once the new permission boundary is registered, you can then send a delegation request to customers to update the IAM role and attach the newly registered permission boundary. See the Examples section for more details.
## Example Use Case: Data Processing Workload
Consider a product provider that runs a data processing workload in customer accounts. The provider needs to set up infrastructure during initial onboarding, but also requires ongoing access to operate the workload.
*Temporary permissions (for initial setup):*
+ Create Amazon EC2 instances, VPC, and security groups
+ Create an Amazon S3 bucket for processed data
+ Create an IAM role for ongoing operations
+ Attach a permission boundary to the IAM role
*Long-term permissions (IAM role with permission boundary for ongoing operations):*
+ Start and stop Amazon EC2 instances to run processing jobs
+ Read input data from Amazon S3 bucket
+ Write processed results to Amazon S3 bucket
The temporary permissions are used once during onboarding to configure the infrastructure. The IAM role created during this process has a permission boundary that limits its maximum permissions to only the operations needed for ongoing workload management. This ensures that even if the role's policies are modified, it cannot exceed the permissions defined in the boundary.
# Policy evaluation guidelines
AWS will evaluate your submitted policies against a set of guidelines. The same evaluation guidelines apply to both policy templates and permission boundaries, with minor differences noted where appropriate.
For the purposes of evaluation, we separate services into distinct groups. The most important distinction is for security-sensitive services, which manage access, credentials, and keys. Policies granting access to these services need to be focused narrowly on the work being done. Security-sensitive services include the following: AWS Identity and Access Management (IAM), AWS Key Management Service (KMS), AWS Resource Access Manager (RAM), AWS IAM Identity Center, AWS Organizations, and AWS Secrets Manager.
A secondary distinction is services that can access data across account boundaries. Policies for these services must include protections to prevent unintentional cross-account access.
## Common validations
All policy statements must follow these guidelines:
+ All statements must include Effect, Action (or NotAction), Resource, and Condition fields in that order
+ All actions within a single statement must be listed alphabetically
+ All ARNs included in the policy must follow the syntax defined in public documentation for the relevant services
+ NotAction fields can only be used in Deny statements
+ Actions in Allow statements must include a service code. Generic wildcards ("\$1") are not allowed
## Security-sensitive service restrictions
The following restrictions apply to security-sensitive services mentioned above:
+ Actions in Allow statements must be more specific than [service]:\$1
+ Actions in Allow statements for temporary access policy templates must not contain wildcards
+ Sensitive actions, such as iam:PassRole or iam:CreateServiceLinkedRole, require additional scoping, such as specific resources or conditional checks. These actions include:
+ IAM role passing
+ IAM role modification actions
+ IAM policy modification actions
+ AWS KMS write or cryptographic operations
+ AWS RAM write or share operations
+ AWS Secrets Manager operations for retrieving or modifying secrets, or modifying resource policies
+ Other actions may use a wildcard resource, such as iam:ListUsers or iam:GetPolicy
+ Actions that manage credentials, such as iam:CreateAccessKey, are blocked
## IAM-specific restrictions
For IAM:
+ Only limited write operations are allowed for IAM roles and policies. You can not request permissions on other IAM resources such as users, groups, and certificates.
+ Policy attachment or inline policy management actions are limited to roles with a permission boundary. Permission boundaries must be partner-supplied or on a list of allowed AWS managed policies. AWS managed policies may be allowed if they do not grant highly privileged or administrative permissions. For example, AWS managed policies for specific job functions or the SecurityAudit policy may be acceptable. AWS will review each AWS managed policy on a case-by-case basis during the onboarding process.
+ Policy management is only allowed for policies with a partner-specific path: arn:aws:iam::@\$1AccountId\$1:policy/partner\$1domain.com/[feature]\$1
+ Tags may only be applied during resource creation, and only for roles and policies
+ iam:PassRole checks must match a specific name or path prefix
## AWS STS-specific restrictions
For AWS STS:
+ sts:AssumeRole must be scoped to a specific role ARN, role ARN prefix, or limited to a set of accounts or organization ID/organizational unit
## IAM Identity Center restrictions
For AWS IAM Identity Center, the following actions are blocked:
+ All actions dealing with permissions management (e.g., sso:AttachCustomerManagedPolicyReferenceToPermissionSet)
+ User, group, and membership modifications for AWS Identity Store
+ Tag management
## AWS Organizations restrictions
For AWS Organizations, only read actions will be allowed.
## Additional service-specific validations
+ Actions that acquire secrets or credentials, such as glue:GetConnection or redshift:GetClusterCredentials, must have conditions matching either full ARNs, ARN prefixes, or tags
+ For Amazon Redshift: redshift:GetClusterCredentials is only allowed on a specific database name, and redshift:GetClusterCredentialsWithIAM is only allowed on a specific workgroup name
**Note**
When managing IAM resources in the account, we recommend using a path that indicates your name, e.g., arn:aws:iam::111122223333:role/partner.com/rolename. This will help differentiate the resources associated with your integration and make discovery, audit, and analysis easier for customers.
## Cross-account access requirements
Statements that potentially allow cross-account access must include at least one of the following:
+ A condition specifying the account or organization for the resource (e.g., aws:ResourceOrgId matching one or more expected values)
+ A Resource field that includes a specific account (e.g., arn:aws:sqs:\$1:111122223333:\$1)
+ A Resource field that includes a non-wildcard account and a full resource name (e.g., arn:aws:s3:::full-bucket-name)
**Note**
Cross-account access is a sensitive capability that requires clear business justification. AWS will carefully review the need for cross-account access during the onboarding process.
# Policy templates
Policy templates are a new IAM construct designed for defining temporary permissions that partners request in customers' accounts. Like regular IAM policies, they define permissions using statements with Effect, Action, Resource, and Condition elements. The key difference is that policy templates include parameters (such as @\$1bucketName\$1) that are replaced with actual values when you create a delegation request.
## How Policy Templates Work
As part of the onboarding process, you register your policy templates with AWS. AWS assigns each template a unique ARN that you reference when creating delegation requests.
When you create a delegation request, you specify:
+ The policy template ARN
+ Parameter values to substitute into the template
AWS combines the template with your parameter values to generate a standard IAM policy. Customers review this final rendered policy when approving your delegation request, seeing exactly what permissions will be granted.
**Note**
The final rendered policy has a maximum size limit of 2048 characters.
Here's a simple example showing how template substitution works.
Policy Template:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Resource": "arn:aws:s3:::@{bucketName}/*"
}
]
}
```
Parameters Provided in Delegation Request:
```
{
"Name": "bucketName",
"Values": ["customer-data-bucket"],
"Type": "String"
}
```
Final rendered policy (what customers see):
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Resource": "arn:aws:s3:::customer-data-bucket/*"
}
]
}
```
## Template Syntax
Policy templates use two key features to provide flexibility: parameter substitution and conditional statements. Parameter substitution allows you to define placeholders in your template that are replaced with actual values when creating a delegation request. Conditional statements allow you to include or exclude entire policy statements based on parameter values.
### Parameter Substitution and Types
Use the @\$1parameterName\$1 syntax to define parameters in your policy template. When creating a delegation request, you must specify the type for each parameter.
#### String
A single value that is substituted directly into the template.
Template:
```
"Resource": "arn:aws:s3:::@{bucketName}/*"
```
Parameters:
```
{
"Name": "bucketName",
"Values": ["my-bucket"],
"Type": "String"
}
```
Rendered result:
```
"Resource": "arn:aws:s3:::my-bucket/*"
```
#### StringList
Multiple values that generate multiple resource entries. When a StringList parameter is used in a resource ARN, it expands to create separate resource entries for each value.
Template:
```
"Resource": "arn:aws:s3:::@{bucketNames}/*"
```
Parameters:
```
{
"Name": "bucketNames",
"Values": ["bucket-1", "bucket-2"],
"Type": "StringList"
}
```
Rendered result:
```
"Resource": [
"arn:aws:s3:::bucket-1/*",
"arn:aws:s3:::bucket-2/*"
]
```
#### Cross-Product Behavior
When multiple parameters are used in the same resource ARN, StringList parameters create a cross-product of all combinations.
Template:
```
"Resource": "arn:aws:s3:::@{bucketNames}/@{prefix}/*"
```
Parameters:
```
[
{
"Name": "bucketNames",
"Values": ["bucket-1", "bucket-2"],
"Type": "StringList"
},
{
"Name": "prefix",
"Values": ["data"],
"Type": "String"
}
]
```
Rendered result:
```
"Resource": [
"arn:aws:s3:::bucket-1/data/*",
"arn:aws:s3:::bucket-2/data/*"
]
```
### Conditional Statements
Use the @Enabled directive to conditionally include or exclude entire statements based on parameter values.
Syntax:
+ @Enabled: "parameterName" - Include the statement when parameter value is "True"
+ @Enabled: "\$1parameterName" - Include the statement when parameter value is NOT "True" (negation)
Template:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": "*"
},
{
"@Enabled": "ENABLE_S3_WRITE",
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": "arn:aws:s3:::@{bucketName}/*"
}
]
}
```
Parameters (when ENABLE\$1S3\$1WRITE is "True"):
```
[
{
"Name": "bucketName",
"Values": ["my-bucket"],
"Type": "String"
},
{
"Name": "ENABLE_S3_WRITE",
"Values": ["True"],
"Type": "String"
}
]
```
Rendered result:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": "arn:aws:s3:::my-bucket/*"
}
]
}
```
Parameters (when ENABLE\$1S3\$1WRITE is "False"):
```
[
{
"Name": "bucketName",
"Values": ["my-bucket"],
"Type": "String"
},
{
"Name": "ENABLE_S3_WRITE",
"Values": ["False"],
"Type": "String"
}
]
```
Rendered result:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": "*"
}
]
}
```
When ENABLE\$1S3\$1WRITE is set to "True", the conditional statement is included. When set to "False", the statement is excluded from the rendered policy.
## Additional Examples
The following examples demonstrate common patterns for using policy templates in temporary delegation. They focus on creating IAM roles with permission boundaries for long-term access and show different strategies for scoping permissions to specific resources. These examples illustrate how to balance flexibility with security by using techniques such as ARN prefixes, resource tagging, and permission boundary updates.
### Example 1: Granting Long-Term Access to Specific Resources
The following permission boundary is submitted as "SQSAccessorBoundary" for "partner.com":
```
{
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:ReceiveMessage",
"sqs:SendMessage"
],
"Resource": "arn:aws:sqs:*:*:*",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "${aws:PrincipalAccount}"
}
}
}
```
**Note**
This includes a same-account condition to avoid granting access to queues in other accounts with open resource policies. A direct reference to the customer's account ID cannot be included because the boundary is shared across all customers and cannot be templated.
Since this is the first version of this policy, its ARN is arn:aws:iam::partner:policy/permissions-boundary/partner.com/SQSAccessorBoundary\$12025\$101\$115
The following policy template is submitted for temporary access permissions:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:ListQueues"
],
"Resource": "arn:aws:sqs:*:*:*"
},
{
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:PutRolePermissionsBoundary",
"iam:PutRolePolicy"
],
"Resource": "arn:aws:iam::@{AccountId}:role/partner.com/SQSAccessor",
"Condition": {
"StringEquals": {
"iam:PermissionsBoundary": "arn:aws:iam::partner:policy/permissions-boundary/partner.com/SQSAccessorBoundary_2025_01_15"
}
}
}
]
}
```
### Example 2: Using ARN Prefixes
The permission boundary can specify a resource ARN prefix to limit access:
```
"Resource": "arn:aws:sqs:*:@{AccountId}:PartnerPrefix*"
```
This limits access to only the resources with that prefix, reducing the scope of accessible resources.
### Example 3: Using Tags for Resource Access Control
You can tag resources during temporary delegated access and rely on those tags for long-term access control.
Permission boundary allowing access to tagged resources:
```
{
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:ReceiveMessage",
"sqs:SendMessage"
],
"Resource": "arn:aws:sqs:*:*:*",
"Condition": {
"Null": {
"aws:ResourceTag/ManagedByPartnerDotCom": "false"
},
"StringEquals": {
"aws:ResourceAccount": "${aws:PrincipalAccount}"
}
}
}
```
Policy template to tag new queues on creation:
```
{
"Effect": "Allow",
"Action": [
"sqs:CreateQueue",
"sqs:TagQueue"
],
"Resource": "arn:aws:sqs:*:*:*",
"Condition": {
"Null": {
"aws:RequestTag/ManagedByPartnerDotCom": "false"
}
}
}
```
Policy template to tag pre-existing queues and create the role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:TagQueue"
],
"Resource": "arn:aws:sqs:*:@{AccountId}:@{QueueName}",
"Condition": {
"ForAllValues:StringEquals": {
"aws:TagKeys": "ManagedByPartnerDotCom"
}
}
},
{
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:PutRolePermissionsBoundary",
"iam:PutRolePolicy"
],
"Resource": "arn:aws:iam::@{AccountId}:role/partner.com/SQSAccessor",
"Condition": {
"StringEquals": {
"iam:PermissionsBoundary": "arn:aws:iam::partner:policy/permissions-boundary/partner.com/SQSAccessorBoundary_2025_01_15"
}
}
}
]
}
```
This approach allows customers to explicitly confirm which specific resources can be accessed long-term.
### Example 4: Updating the Permission Boundary
To update a permission boundary, register a new version with a new date suffix and request permission to replace it.
Updated permission boundary with additional permission:
```
{
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:PurgeQueue",
"sqs:ReceiveMessage",
"sqs:SendMessage"
],
"Resource": "arn:aws:sqs:*:*:*",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "${aws:PrincipalAccount}"
}
}
}
```
As the second version, this policy has the ARN: arn:aws:iam::partner:policy/permissions-boundary/partner.com/SQSAccessorBoundary\$12025\$101\$120
Policy template to update the permission boundary on the existing role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:PutRolePermissionsBoundary"
],
"Resource": "arn:aws:iam::@{AccountId}:role/partner.com/SQSAccessor",
"Condition": {
"StringEquals": {
"iam:PermissionsBoundary": "arn:aws:iam::partner:policy/permissions-boundary/partner.com/SQSAccessorBoundary_2025_01_20"
}
}
}
]
}
```
Customers must approve this delegation request to update the permission boundary on the existing role.
# Building your integration
## Understanding the Request Lifecycle
Before building your integration, it's important to understand how delegation requests progress from creation to completion.
### Request States
A delegation request progresses through the following states:
| State | Description |
| --- | --- |
| Unassigned | Request created but not yet associated with a customer account and an IAM principal. The request may have been created without specifying a target account, or with a target account ID but not yet claimed by the account owner. |
| Assigned | Request associated with a customer account and awaiting review |
| Pending Approval | Customer has forwarded the request to an administrator for approval |
| Accepted | Request approved by customer but exchange token not yet released |
| Finalized | Exchange token released to product provider. The delegation period (exchange token validity) begins when the request reaches Finalized state |
| Rejected | Request rejected by customer |
| Expired | Request expired due to inactivity or timeout |
### State Transitions
*Normal Flow (Approval Path)*
+ Unassigned → Assigned: Customer associates the request with their account
+ Assigned → Accepted OR Assigned → Pending Approval: Customer approves the request directly OR forwards to administrator for review
+ Pending Approval → Accepted: Administrator approves the request
+ Accepted → Finalized: Customer releases the exchange token
*Rejection Path*
+ Assigned → Rejected: Customer rejects the request
+ Pending Approval → Rejected: Administrator rejects the request
+ Accepted → Rejected: Customer revokes approval before releasing token
*Expiration Path*
Requests automatically expire if no action is taken within the specified timeframe:
+ Unassigned → Expired (1 day)
+ Assigned → Expired (7 days)
+ Pending Approval → Expired (7 days)
+ Accepted → Expired (7 days)
+ Rejected → Expired (7 days)
+ Finalized → Expired (7 days)
*Terminal States*
The following states are terminal (no further transitions):
+ Finalized: Exchange Token sent
+ Rejected: Request was denied
+ Expired: Request timed out or delegation period ended
Expired requests are eventually deleted from the system after the retention period.
### Managing delegation request states in your application
As a partner, you must track delegation request states in your system and surface them to your customers. When you receive SNS notifications about state changes, store these updates in your backend and reflect them in your customer-facing UI. Pay special attention to the Pending Approval state—when a customer forwards a request to an administrator for review, AWS sends a Pending Approval notification to you. Requests can remain in this state for up to 7 days while waiting for administrator action. During this time, show customers that their request is pending administrator approval in your application. Consider providing a deep link to the AWS Console where customers can check the request status or follow up with their administrator. Properly handling the state machine in your backend and surfacing the correct state information to customers at each stage is important for a good integration experience.
![\[alt text not found\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/delegation-states.png)
## Configuring Notifications
IAM uses Amazon Simple Notification Service (SNS) to communicate delegation request state changes to you. When you create a delegation request, you must provide an SNS topic ARN from your registered AWS account. IAM will publish messages to this topic for important events, including when customers approve or reject requests and when the exchange token is ready.
**Note**
SNS topics cannot be in opt-in AWS Regions. Your SNS topic must be in an AWS Region that is enabled by default. For a list of opt-in Regions, see Managing AWS Regions in the AWS Account Management guide.
### SNS Topic Configuration
To receive delegation request notifications, you must configure your SNS topic to grant IAM permissions to publish messages to it. Add the following policy statement to your SNS topic policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowIAMServiceToPublish",
"Effect": "Allow",
"Principal": {
"Service": "iam.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:REGION:ACCOUNT-ID:TOPIC-NAME"
}
]
}
```
**Important**
The SNS topic must be in one of your registered AWS accounts. IAM will not accept SNS topics from other accounts. If the topic policy is not correctly configured, you will not receive state change notifications or the exchange token.
### Notification Types
IAM sends two types of notifications:
*StateChange Notifications*
Sent when a delegation request transitions to a new state (Assigned, Pending Approval, Accepted, Finalized, Rejected, Expired).
*ExchangeToken Notifications*
Sent when a customer releases the delegation token (state Finalized). This notification includes the exchange token you need to obtain credentials.
### Notification States
You will receive notifications for the following delegation request states:
| State | Notification Type | Description |
| --- | --- | --- |
| ASSIGNED | StateChange | Request has been associated with a customer account |
| PENDING APPROVAL | StateChange | Customer has forwarded the request to an administrator for approval |
| ACCEPTED | StateChange | Customer has approved the request but not yet released the token |
| FINALIZED | StateChange | Customer has released the exchange token |
| FINALIZED | ExchangeToken | This notification contains the Exchange Token |
| REJECTED | StateChange | Customer has rejected the request |
| EXPIRED | StateChange | Request expired before completion |
### Notification Message Format
IAM publishes standard SNS notifications. The delegation request information is contained in the Message field as a JSON string.
*Common Fields (All Notifications)*
| Field | Type | Description |
| --- | --- | --- |
| Type | String | Either "StateChange" or "ExchangeToken" |
| RequestId | String | The IAM delegation request ID |
| RequestorWorkflowId | String | The workflow ID you provided when creating the request |
| State | String | Current state of the request |
| OwnerAccountId | String | Customer's AWS account ID |
| UpdatedAt | String | Timestamp when the state changed (ISO 8601 format) |
*Additional Fields (ExchangeToken Notifications Only)*
| Field | Type | Description |
| --- | --- | --- |
| ExchangeToken | String | The token to exchange for credentials using AWS STS GetDelegatedAccessToken API |
| ExpiresAt | String | When the delegated access expires (ISO 8601 format) |
### Example Notifications
*StateChange Notification*
```
{
"Type": "Notification",
"MessageId": "61ee8ad4-6eec-56b5-8f3d-eba57556aa13",
"TopicArn": "arn:aws:sns:us-east-1:123456789012:partner-notifications",
"Message": "{\"RequestorWorkflowId\":\"workflow-12345\",\"Type\":\"StateChange\",\"RequestId\":\"dr-abc123\",\"State\":\"ACCEPTED\",\"OwnerAccountId\":\"111122223333\",\"UpdatedAt\":\"2025-01-15T10:30:00.123Z\"}",
"Timestamp": "2025-01-15T10:30:00.456Z",
"SignatureVersion": "1",
"Signature": "...",
"SigningCertURL": "...",
"UnsubscribeURL": "..."
}
```
*ExchangeToken Notification*
```
{
"Type": "Notification",
"MessageId": "e44e5435-c72c-5333-aba3-354406782f5b",
"TopicArn": "arn:aws:sns:us-east-1:123456789012:partner-notifications",
"Message": "{\"RequestId\":\"dr-abc123\",\"RequestorWorkflowId\":\"workflow-12345\",\"State\":\"FINALIZED\",\"OwnerAccountId\":\"111122223333\",\"ExchangeToken\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\"ExpiresAt\":\"2025-01-15T18:30:00.123Z\",\"UpdatedAt\":\"2025-01-15T10:30:00.456Z\",\"Type\":\"ExchangeToken\"}",
"Timestamp": "2025-01-15T10:30:00.789Z",
"SignatureVersion": "1",
"Signature": "...",
"SigningCertURL": "...",
"UnsubscribeURL": "..."
}
```
## Exchange Tokens
An exchange token or a trade in token is issued by IAM when a customer accepts and finalizes a delegation request. The product provider uses this exchange or trade in token to call the AWS STS GetDelegatedAccessToken API to obtain temporary AWS credentials with the permissions customers approved. The exchange token itself does not grant access to your AWS resources; it must be exchanged for actual credentials through AWS STS.
The exchange token can only be redeemed by the product provider account that created the delegation request. The requesting account is embedded in the token, ensuring that only the authorized product provider can obtain credentials to access customer account.
### Access Duration
The delegation period starts when customer releases the exchange token, not when the product provider redeems it. Once customer releases the token:
+ The product provider receives the token via SNS notification
+ They can immediately exchange it for credentials
+ Credentials expire at: release time \$1 approved duration
+ The product provider can exchange the token multiple times before expiration to obtain fresh credentials if needed
### Multiple Redemptions
Product providers can exchange the token multiple times during the validity period to obtain fresh credentials. However, all credentials obtained from the same exchange token expire at the same time, based on when you released the token.
Example: If you approve a 2-hour delegation request and release the token at 10:00 AM:
| Token Release Time | Token Exchange Time | Credential Expiry | Usable Time |
| --- | --- | --- | --- |
| 10:00 am | 10:00 am | 12:00 pm | 2 hours |
| 10:00 am | 10:20 am | 12:00 pm | 1 hour 40 minutes |
| 10:00 am | 11:40 am | 12:00 pm | 20 minutes |
| 10:00 am | 12:10 pm | Failed (token expired) | 0 minutes |
As shown in the table, exchanging the token later in the validity period results in less usable time for the product provider.