> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quiverstone.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory Roles

> Deploy inventory roles so Quiverstone can discover and monitor AWS accounts in your Organization

Inventory roles provide read-only access to AWS Organizations, enabling Quiverstone to automatically discover accounts in your organization. Deploy these roles to enable organization-level account discovery and monitoring.

## When to Use Inventory Roles

* Automatically discover all accounts in your AWS Organization
* Monitor organization structure and account changes
* Enable organization-wide account management in Quiverstone
* Provide read-only access to AWS Organizations API
* Deploy from management account or delegated administrator account

## Direct Inventory Deployment

Direct inventory access is the most common deployment method where Quiverstone directly assumes the inventory role in your organization's management or delegated administrator account.

<Steps>
  <Step title="Launch CloudFormation Template">
    Click the button below to launch the direct organization inventory role template in your management or delegated administrator account:

    [    <img src="https://mintcdn.com/quiverstone/VPfcLjxCv7tUOPiQ/assets/stack.png?fit=max&auto=format&n=VPfcLjxCv7tUOPiQ&q=85&s=7735bb0827dba16381ad6a3824ec89ef" alt="Launch Stack" width="1000" height="250" data-path="assets/stack.png" />](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://s3.us-east-2.amazonaws.com/assets.quiverstone.io/role-catalog/inventory/direct-org-inventory-role.yaml\&stackName=quiverstone-direct-org-inventory-role)
  </Step>

  <Step title="Configure Essential Parameters">
    **Role Name** (`pRoleName`): Name for the inventory role (Default: QuiverstoneDirectOrgInventory)

    <Warning>
      **Security Best Practice**: Change the default role name to a custom value unique to your organization. Using default role names makes it easier for unauthorized parties to discover and potentially target your roles.
    </Warning>

    **External ID** (`pExternalId`): Security token for role assumption

    <Warning>
      **Required for Production**: Always configure an External ID for production deployments. This prevents confused deputy attacks and unauthorized role assumptions.

      * Generate a unique random string (minimum 32 characters)
      * Store securely - you'll need this when configuring Quiverstone
      * Never share or commit External IDs to version control
    </Warning>
  </Step>

  <Step title="Create Stack">
    Review the parameters and create the CloudFormation stack. Wait for the stack to reach CREATE\_COMPLETE status.
  </Step>

  <Step title="Copy Role ARN">
    From the stack Outputs tab, copy the role ARN (e.g., `arn:aws:iam::123456789012:role/QuiverstoneDirectOrgInventory`)
  </Step>

  <Step title="Configure Quiverstone">
    In Quiverstone, add the organization using:

    * Role ARN from the previous step
    * External ID you configured in the template
  </Step>
</Steps>

<Note>
  The inventory role only provides read-only access to AWS Organizations. It cannot make changes to your organization structure or account settings. For detailed deployment information, see the [Inventory Roles Reference](/setup/iam-roles/inventory).
</Note>

## Chained Inventory Deployment

Chained inventory access adds an intermediate security layer by routing role assumptions through a trusted account you control. Use this when security policies require additional controls beyond direct access to your management account.

<Warning>
  Chained inventory requires two deployments: first the intermediate role, then the destination inventory role. Deploy in this order.
</Warning>

<Steps>
  <Step title="Deploy Intermediate Role (First)">
    Deploy the intermediate role to your trusted/intermediate account:

    [    <img src="https://mintcdn.com/quiverstone/VPfcLjxCv7tUOPiQ/assets/stack.png?fit=max&auto=format&n=VPfcLjxCv7tUOPiQ&q=85&s=7735bb0827dba16381ad6a3824ec89ef" alt="Launch Stack" width="1000" height="250" data-path="assets/stack.png" />](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://s3.us-east-2.amazonaws.com/assets.quiverstone.io/role-catalog/intermediate/trusted-intermediate-role.yaml\&stackName=quiverstone-trusted-intermediate-role)

    **Essential Parameters:**

    * **Role Name** (`pIntermediateRoleName`): Default is QuiverstoneTrustedIntermediate
      <Warning>Change this to a custom role name for enhanced security</Warning>
    * **External ID** (`pExternalId`): Generate unique random string (minimum 32 characters)
      <Warning>Required for production - never use default or empty values</Warning>
    * **Assume Role Scope** (`pAssumeRoleScope`): Use `specific-role-any-account` (recommended)
    * **Destination Role Name** (`pDestinationRoleName`): QuiverstoneChainedOrgInventory
      <Warning>Change this to match your custom destination role name</Warning>

    <Note>
      If you already have an intermediate role deployed, you can reuse it. Skip to Step 2.
    </Note>

    Copy the intermediate role ARN and External ID from the stack outputs.
  </Step>

  <Step title="Deploy Chained Inventory Role (Second)">
    Deploy the chained inventory role to your management or delegated administrator account:

    [    <img src="https://mintcdn.com/quiverstone/VPfcLjxCv7tUOPiQ/assets/stack.png?fit=max&auto=format&n=VPfcLjxCv7tUOPiQ&q=85&s=7735bb0827dba16381ad6a3824ec89ef" alt="Launch Stack" width="1000" height="250" data-path="assets/stack.png" />](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://s3.us-east-2.amazonaws.com/assets.quiverstone.io/role-catalog/inventory/chained-org-inventory-role.yaml\&stackName=quiverstone-chained-org-inventory-role)

    **Essential Parameters:**

    * **Role Name** (`pChainedOrgInventoryRoleName`): Default is QuiverstoneChainedOrgInventory
      <Warning>Change this to a custom role name for enhanced security</Warning>
    * **External ID** (`pExternalId`): Generate unique random string (can be different from intermediate)
      <Warning>Required for production - use a different value than the intermediate role External ID</Warning>
    * **Intermediate Account ID** (`pIntermediateAccountId`): Account ID where intermediate role is deployed
    * **Intermediate Role Name** (`pIntermediateRoleName`): Name of intermediate role (default: QuiverstoneTrustedIntermediate)
      <Warning>Update this if you changed the intermediate role name</Warning>
    * **Trust Principals** (`pTrustPrincipals`): Use `Named` for enhanced security (recommended)

    Copy the chained inventory role ARN from the stack outputs.
  </Step>

  <Step title="Configure Quiverstone">
    In Quiverstone, configure chained inventory access using:

    * Intermediate role ARN and External ID (from Step 1)
    * Destination role ARN and External ID (from Step 2)
  </Step>
</Steps>

<Note>
  For detailed deployment information, see the [Inventory Roles Reference](/setup/iam-roles/inventory).
</Note>

## Standalone Account Inventory

For AWS accounts that are not part of an organization, you can deploy a standalone account inventory role. This provides basic account information without organization-level discovery.

For detailed information about standalone account inventory deployment, see the [Inventory Roles Reference](/setup/iam-roles/inventory).

## Next Steps

* **Deploy access roles**: After inventory setup, deploy access roles to individual accounts
* **Monitor organization**: Quiverstone will automatically discover new accounts added to your organization
* **Review permissions**: Verify the inventory role has appropriate read-only access
* **Test discovery**: Confirm Quiverstone can discover all accounts in your organization

## Detailed Deployment Information

For comprehensive information about all inventory role templates, account types, permissions, deployment scenarios, and troubleshooting, see the [Inventory Roles Reference](/setup/iam-roles/inventory).
