# Amazon Q index for independent software vendors (ISVs)
<a name="isv"></a>

As an ISV, you can leverage Amazon Q index to access and integrate your customers' enterprise data into your applications. This integration enables you to enhance your applications with generative AI capabilities powered by your customers' data, without having to directly connect to or index individual data sources. Your customers simply need to add you as a data accessor and provide you with the configuration details, allowing you to retrieve relevant content through the `SearchRelevantContent` API operation. 

Alternatively, you can create a Amazon Q application environment on behalf of the customer and add their data sources yourself. The Amazon Q index will then be able to retrieve the relevant content through the `SearchRelevantContent` API operation. For more information, see [Creating an Amazon Q index on behalf of a customer](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/isv-creating-index). 

**Topics**
+ [Key concepts](isv-key-concepts.md)
+ [Prerequisites](isv-prerequisites.md)
+ [Information to be provided to the Amazon Q Business team](isv-info-to-provide.md)
+ [Getting access to your customer's Amazon Q index](isv-getting-access.md)
+ [Accessing a customer's Amazon Q index as a data accessor using cross-account access](#isv-accessing-cross-account)
+ [Creating an Amazon Q index on behalf of a customer](isv-creating-index.md)
+ [Troubleshooting](isv-troubleshooting.md)

# Key concepts
<a name="isv-key-concepts"></a>

Amazon Q index  
A comprehensive collection of a company's data that can be queried to build enhanced application experiences. It serves as the foundation for retrieving relevant content across various enterprise data sources.  
Organizations that are Amazon Q Business customers and would like to connect their data sources with a supported ISV can add the ISV as a *data accessor*. For more information, see [Data accessors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-accessors.html).

`SearchRelevantContent` API operation  
This API operation enables ISVs to access the Amazon Q index. It supports keyword, semantic, and hybrid queries—allowing for flexible data retrieval options.

AWS Identity and Access Management IAM Identity CenterManaged Application  
Amazon Q Business manages end user access to a customer's Amazon Q index using IAWS Identity and Access Management IAM Identity Center.

Resource-based policy  
A resource-based policy is an IAM policy that's attached to a resource. Amazon Q Business attaches [a resource-based policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html) to an Amazon Q Business application environment during the data accessor setup. This policy grants the ISV's AWS account the necessary permissions to access content for the customer's end users from the customer's data sources through the `SearchRelevantContent` API operation. By attaching a resource-based policy to the data accessor's AWS account, it allows access to the Amazon Q index of the application environment. For more information, see [Data accessors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-accessors.html).

 

# Prerequisites
<a name="isv-prerequisites"></a>

1. Create an AWS account. For more information, see [Create an AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html).

1. [Sign up](https://aws.amazon.com/q/software-provider) as an independent software provider or vendor (ISV) for Amazon Q index.

1. Complete the AWS verification process to ensure legitimacy and prevent impersonation.

1. The following tabs provide the instructions for how to retrieve your `Tenant ID` for each ISV.

------
#### [ Asana ]

In Asana, the Tenant ID in Amazon Q Business Data Accessor is called the `domain ID`. You can use the following instructions to retrieve the Asana Tenant ID

 

1. Choose your account profile picture and select Admin Console.

2. Select Settings.

3. Scroll to Domain Settings to retrieve the Tenant ID.

------
#### [ PagerDuty ]

In PagerDuty, the tenant ID in Amazon Q Business Data Accessor is called the tenant ID. You can use the following instructions to retrieve the PagerDuty the Tenant ID

 

1. Select the User Icon.

2. Select Account Settings.

3. Select the PagerDuty Advance tab.

4. Toggle Enable Amazon Q to the on position.

5. The PagerDuty Tenant ID is now available from the Amazon Q Business Configuration Values modal.

------
#### [ Kore.ai (AIforWork) ]

In AIforWork, the Tenant ID is displayed directly in the setup form. You can use the following instructions to retrieve the Kore.ai Tenant ID:

 

1. Navigate to AIforWork platform.

2. When setting up an Enterprise Knowledge or Search Agent, choose **Q for Business**.

3. In the setup form that opens, the Tenant ID is displayed and ready to copy.

------
#### [ Revinova ]

The Portal ID in Revinova is the Tenant ID for Amazon Q Business Data Accessor. You can use the instructions below to retrieve the Portal ID from Revinova.

1. Log in to the admin console.

1. Navigate to the portals dashboard using the **Portals** menu under the settings menu collection.

1. In the portal's grid, hover on the header of any of the columns and click on the hamburger menu shown in the column to open the column options context menu.

1. Click on the grid icon available on the top right corner of the column options context menu.

1. Select **ID** from the list of columns available for display, and it will show the portal IDs in the grid.

1. You can get the ID for the portal from the corresponding row.

------
#### [ Planview ]

Your Planview Tenant ID is a unique identifier in UUID/GUID format (e.g., 12345678-1234-1234-1234-123456789abc).

For Planview, the Tenant ID information can be found in their integration documentation. You can use the following resource to retrieve the Tenant ID for Planview Viz integration with Amazon Q Business.

1. Refer to the [Planview Amazon Q Business Integration FAQ](https://success.planview.com/Planview_Viz/FAQs/General/Planview_Amazon_Q_Business_Integration_FAQ) for detailed instructions on retrieving your Tenant ID.

**Note**  
Planview data accessor is only available in the `us-west-2` region.

------
#### [ Amplience ]

For Amplience, the Tenant ID is the Hub ID. You can use the following instructions to retrieve the Amplience Tenant ID.

1. Within Amplience Dynamic Content, switch into the Hub you wish to connect.

1. Select the settings icon in the top right corner and select the **Properties** menu item.

1. The Hub ID will be displayed with a copy to clipboard option.

------
#### [ Saviynt ]

For Saviynt, the Tenant ID is the FQDN from the Saviynt Console. You can use the following instructions to retrieve the Saviynt FQDN.

The URL will look similar to this example https://ispm-dev.saviyntcloud.com/ and the tenant id from this example will be "ispm-dev.saviyntcloud.com"

------
#### [ Webex by CISCO ]

In Webex, the tenant ID in Amazon Q Business Data Accessor is called the Organization ID. You can use the following instructions to retrieve the Webex Tenant ID.

1. Login in Cisco Control Hub.

1. Go to Account->Info page.

1. Copy the Organization ID.

------
#### [ Fireflies.ai ]

When prompted for Tenant ID, please enter Team ID

------
#### [ Miro ]

For Miro, the Tenant ID is Organization ID. Organization admins can navigate to the 'Organization profile' page and get the id from the address bar.

------
#### [ SUSE Rancher for Amazon Web Services ]

For SUSE Rancher for Amazon Web Services, the Tenant ID is tenant-uid. The tenant-uid can be found within the application in the about info in the top right of the screen.

------
#### [ CXone Mpower ]

For CXone Mpower, the Tenant ID required for the Amazon Q Business Data Accessor is displayed on your My Profile page. To access this page,

- In the upper‑right corner of any page in the platform, click your initials.

- Select My Profile from the menu.

- On the General tab of the My Profile page, locate your Tenant ID.

------

# Information to be provided to the Amazon Q Business team
<a name="isv-info-to-provide"></a>

Before an independent software provider or vendor (ISV) can become a verified data accessor, they must provide either an Auth code or Trusted token issuer (TTI) configuration information to the Amazon Q Business team.

Prerequisite for both Auth code and TTI configurations.

`tenantID`

The `tenantID` is a unique identifier for your application tenant. Each application might have different terms for a tenant such as Workspace ID for Slack or Domain ID for Asana. You can review the [Prerequisites](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/isv-prerequisites.html) page to see how to retrieve the `TenantId` for your application.

------
#### [ Auth code ]

**Prerequisites:**
+ The display name to list on the AWS Management Console
+ The business logo that Amazon Q Business customers will select
+ The redirect URL for the `oAuth` authorization code flow. 
**Note**  
`oAuth` authorization code flow is an industry standard for third-party applications to obtain user access permissions. In the authorization code flow, ISV receives an auth code from AWS and exchanges the auth code for an ID token.
+ The ISVs must create the following AWS Identity and Access Management (IAM) role with the necessary permissions and trust policy to interact with the Amazon Q Business services and APIs. This IAM role is granted access as a data accessor when Amazon Q Business customers provide access to their Amazon Q index. For more information, see [IAM role terms and concepts](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#id_roles_terms-and-concepts) and [Create a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html).
  + **ISV IAM role**  
****  

    ```
    {
        "Version":"2012-10-17",		 	 	 
        "Statement": [
            {
                "Action": [
                    "qbusiness:SearchRelevantContent",
                    "sso-oauth:CreateTokenWithIAM",
                    "kms:Decrypt",
                    "sts:SetContext"
                ],
                "Resource": "*",
                "Effect": "Allow",
                "Sid": "MultiServicePermissions"
            }
        ]
    }
    ```
  + **ISV IAM role trust policy**  
****  

    ```
    {
        "Version":"2012-10-17",		 	 	 
        "Statement": [
            {
                "Sid": "ISVRoleTrustPolicy",
                "Effect": "Allow",
                "Principal": {
                    "AWS": [
                        "arn:aws:iam::111122223333:role/YourApplicationRole"
                    ]
                },
                "Action": [
                    "sts:AssumeRole",
                    "sts:SetContext",
                    "sts:TagSession"
                ]
            }
        ]
    }
    ```
  + ISV `tenantId`
    + What is `tenantId`?

      The `tenantID` is a unique identifier for your application tenant. Each application might have different terms for a tenant such as Workspace ID for Slack or Domain ID for Asana. 
    + Where do you find the `tenantId`?

      Provide info as to where can the IT Admin of an enterprise can find this information on the ISV.

------
#### [ TTI ]

**Prerequisites:**
+ The display name to list on the AWS Management Console
+ The business logo that Amazon Q Business customers will select
+ OIDC ClientId which can used to generate tokens for all the customers - The OAuth 2.0 authorization server (the trusted token issuer) that creates the token must have an [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-discovery-1_0.html) discovery endpoint that IAM Identity Center can use to obtain public keys to verify the token signatures. For more information, see [OIDC discovery endpoint URL (issuer URL)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#id_roles_terms-and-concepts).
+ Discovery endpoint/[Issuer URL](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) - The entity that issued the token. This value must match the value that is configured in the OIDC discovery endpoint (issuer URL) in the trusted token issuer.

**Note**  
 [Trusted token issuer(App level authentication)](https://docs.aws.amazon.com//singlesignon/latest/userguide/trusted-token-issuer-configuration-settings.html#oidc-discovery-endpoint-url) - A trusted token issuer is an OAuth 2.0 authorization server that creates signed tokens. These tokens authorize applications that initiate requests (requesting applications) for access to AWS managed applications (receiving applications).

The ISVs must create the following AWS Identity and Access Management (IAM) role with the necessary permissions and trust policy to interact with the Amazon Q Business services and APIs. This IAM role is granted access as a data accessor when Amazon Q Business customers provide access to their Amazon Q index. For more information, see [IAM role terms and concepts](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#id_roles_terms-and-concepts) and [Create a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html).
+ **ISV IAM role**

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Action": [
                  "qbusiness:SearchRelevantContent",
                  "sso-oauth:CreateTokenWithIAM",
                  "kms:Decrypt",
                  "sts:SetContext"
              ],
              "Resource": "*",
              "Effect": "Allow",
              "Sid": "MultiServicePermissions"
          }
      ]
  }
  ```

------
+ **ISV IAM role trust policy**

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Sid": "ISVRoleTrustPolicy",
              "Effect": "Allow",
              "Principal": {
                  "AWS": [
                      "arn:aws:iam::111122223333:role/YourApplicationRole"
                  ]
              },
              "Action": [
                  "sts:AssumeRole",
                  "sts:SetContext",
                  "sts:TagSession"
              ]
          }
      ]
  }
  ```

------

------

# Getting access to your customer's Amazon Q index
<a name="isv-getting-access"></a>

There are two non-mutually exclusive ways to get access to a customer's Amazon Q index:

## Customer grants ISVs (data accessors) access to their Amazon Q index
<a name="isv-getting-access-customer-grants"></a>

Amazon Q Business customers add the ISV as a *data accessor* to their Amazon Q Business application environment and underlying Amazon Q index. This includes Amazon Q customers selecting which data sources and end users can retrieve data from and grant ISVs *cross-account* access to their Amazon Q index based on those permissions.

**Note**  
Only ISVs who successfully complete registration with Amazon Q Business can be listed as data accessors.  
Only Amazon Q Business application environments that are created using AWS Identity and Access Management (IAM) identity center (IDC) are supported.

This process gives Amazon Q customers more flexibility, oversight, and control of their Amazon Q index. Amazon Q customers can create their Q index once, and then grant multiple ISVs access to the same minimizing replication of enterprise data and permissions across multiple ISVs. For more information, see [Data accessors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-accessors.html) and [ Accessing a customer's Amazon Q index as a data accessor using cross-account access](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/isv-accessing-cross-account.html).

## The ISV sets up the Amazon Q index on behalf of the customer within their own AWS account
<a name="isv-getting-access-isv-setup"></a>

ISVs can manage the entire process themselves, creating an Amazon Q Business application environment and the underlying Amazon Q index on behalf of each customer in their AWS account. Customers must provide ISV credentials to connect to their data sources.

At the end of both workflows, ISVs can retrieve the data that they have access to using the Amazon Q index.


**Comparison of onboarding options**  

| Scenario | Onboarding with Amazon Q Business | Onboarding with the ISV | 
| --- | --- | --- | 
| Where is the Amazon Q Business application environment created? | Amazon Q Business customer's account | ISV's account | 
| Who sets up Amazon Q Business application environment and underlying Amazon Q index? | Amazon Q Business customer | ISV on behalf of the customer | 

We recommend that ISVs use both onboarding workflows to best support all customers.

## Accessing a customer's Amazon Q index as a data accessor using cross-account access
<a name="isv-accessing-cross-account"></a>

After Amazon Q Business customers give an independent software provider or vendor's (ISV) *data accessor* permissions to retrieve data from their Amazon Q index, the customer or the ISV must connect with one another to get the following configuration details. These configuration parameters are required inputs when they use the `SearchRelevantContent` API operation to perform cross-account access to relevant data from the customer's Amazon Q index. These parameters are accessed from the customer's Amazon Q console in the **Information for data accessor** tab in the **data accessor details** page which is accessed by choosing the accessor **Name** from the **Data accessors** table on the **Data accessors** page of their application environment.

1. Amazon Q Business application ID — This is unique identifier of the Amazon Q Business application environment. It tells the ISV what Amazon Q application environment is associated with the Amazon Q index.

1. The Amazon Q Business application Region — This is the AWS Region where the Amazon Q Business application environment is created.

1. Amazon Q Business retriever ID — This is unique identifier for the retriever. The retriever gets the data from the Amazon Q index configured by the Amazon Q customer.

1. Data accessor application ARN — This is the ISV Amazon Resource Name (ARN). It is used to identify the ISV when it is accessing a customer's Amazon Q index.

1. The Region for the Identity and Access Management (IAM) Identity Center (IDC) instance — This is the AWS Region where the IDC instance of the customer has been created.

With these parameters, the ISV can begin retrieving content from the Amazon Q index by calling the `SearchRelevantContent` API operation. The `SearchRelevantContent` API operation follows Amazon Q Business access control standards by only retrieving data that the customer's end users have been given access to.

### Retrieving data from a customer's Amazon Q index as a data accessor using the SearchRelevantContent API
<a name="isv-retrieving-data"></a>

With valid configuration parameters from the customer, the ISV can use the `SearchRelevantContent` API operation to retrieve user-specific content from the customer's Amazon Q index.

The following are examples of how to use either Auth Code or Trusted Token Issuer based authentication (TTI) to complete this task:

The following tabs provide a procedure to boost document attributes using the console and code examples for the AWS CLI.

------
#### [ Auth code ]

Use the Authentication code method to retrieve user-specific content from the customer's Amazon Q index.

1. The Amazon Q index customer's end user will login to the ISV's application using the existing user login flow.
**Note**  
The ISV doesn't need to change their existing login flow.

1. After the end user successfully logs in, the ISV instructs the user to authenticate to their Amazon Q index through their OIDC providers. For more information, see [Creating an Amazon Q Business application using AWS IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).

   1. `https://oidc.${idc_region}.amazonaws.com/authorize?response_type=code&redirect_uri=${isv_redirect_url}&state={oauth_state}&client_id=${idc_application_arn}`

   1. `isv_redirect_uri` — This is the *redirect URL* that's registered at the ISV registration process. For more information, see [Information to be provided to the Amazon Q Business team](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/isv-info-to-provide).

   1. `oauth_state` — This random string prevents cross-site request forgery (CSRF) attack. For more detail about state parameters in oauth, see [Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters](https://auth0.com/docs/secure/attack-protection/state-parameters) in the auth by Okta guide.

   1. `idc_application_arn` — This is the Amazon Q Business DataAccessor IAM Identity Center application ID that's provided by the customer to the ISV.

1. The end user logs in using the method configured by the customer's Amazon Q administrator. For example, the user's company SSO.

1. The ISV application receives an *auth code* in their *redirect URL*.

1. The ISV application calls the `CreateTokenWithIAM` API operation to get a token with an authorization code. The ISV needs to use the AWS Identity and Access Management (IAM) role that they created during the onboarding process with `tenantId` information in the tags like the following:

   ```
   aws sts assume-role \
         --role-arn ${your_iam_role} \
         --role-session-name test-session \
         --tags Key=qbusiness-dataaccessor:ExternalId,Value=${isv tenantId}
   
   aws sso-oidc create-token-with-iam --client-id "${idc_application_arn}" \
         --redirect-uri "{your_redirect_uri}" \
         --grant-type "authorization_code" \
         --code "${CODE}" --region ${idc_region}
   ```

1. Get the `idToken` field from the response of `CreateTokenWithIAM`. Then, decode the `idToken` and extract `"sts:identity_context"` field from it.

   Using command line:

   ```
   export ID_TOKEN_I = "${response_json_of_create-token-with-iam}"
   export ID_CONTEXT=`jq -R 'split(".") | .[1] | @base64d | fromjson' <<< "$ID_TOKEN_I" | jq -r '."sts:identity_context"'`
   echo "ID_CONTEXT=$ID_CONTEXT\n"
   ```

   Using Python:

   ```
   import json
   import base64
   
   body = "${response_json_of_create-token-with-iam}"
   body_json = base64.urlsafe_b64decode(body.split(".")[1] + '==')
   data = json.loads(body_json)
   print(f"{data['sts:identity_context']}")
   ```

1. Call the [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API with the extracted `sts:identity_context` and the ISV `tenantId` information.

   ```
   aws sts assume-role \
         --role-arn ${your_iam_role} \
         --role-session-name test-session \
         --provided-contexts '[{"ProviderArn": "arn:aws:iam::aws:contextProvider/IdentityCenter", "ContextAssertion": "${value from sts:identity_context}"}]' \
         --tags Key=qbusiness-dataaccessor:ExternalId,Value=${isv tenantId}
   ```

1. Use the AWS Sig V4 credentials returned from the previous step to call `SearchRelevantContent` API.

   ```
   aws qbusiness search-relevant-content \
         --application-id ${qbusiness_application_id} \
         --query-text "What is Amazon Q?" \
         --content-source '{"retriever": {"retrieverId": "${retriever_id}"}}'
   ```

------
#### [ TTI ]

Use the Trusted Token Issuer based authentication (TTI) method to retrieve user-specific content from the customer's Amazon Q index.

1. The Amazon Q index customer's end user will log in to the ISV's application using the existing user login flow.

1.  After the end user successfully logs in, ISV issues a token for the end user using the OIDC client as audience, provided during the onboarding process. 

1.  The ISV application calls the `CreateTokenWithIAM` API operation with the token from step 2. The ISV needs to use the AWS Identity and Access Management (IAM) role that they created during the onboarding process with `tenantId` information in the tags like the following: 

   ```
                                       
   aws sts assume-role \
         --role-arn ${your_iam_role} \
         --role-session-name test-session \
         --tags Key=qbusiness-dataaccessor:ExternalId,Value=${isv tenantId}
         
   aws sso-oidc create-token-with-iam --client-id "${idc_application_arn}" \
         --grant-type "urn:ietf:params:oauth:grant-type:jwt-bearer" \
         --assertion "${isv token generated using oidc client provided during onboarding}" --region ${idc_region}
   ```

1.  Retrieve the `idToken`field from the response of `CreateTokenWithIAM`. Then, decode the `idToken` and extract `sts:identity_context` field from it. 

   1.  Using command line: 

      ```
      export ID_TOKEN_I = "${response_json_of_create-token-with-iam}"
      export ID_CONTEXT=`jq -R 'split(".") | .[1] | @base64d | fromjson' <<< "$ID_TOKEN_I" | jq -r '."sts:identity_context"'`
      echo "ID_CONTEXT=$ID_CONTEXT\n"
      ```

   1.  Using Python: 

      ```
                                                  import json
      import base64
      
      body = "${response_json_of_create-token-with-iam}"
      body_json = base64.urlsafe_b64decode(body.split(".")[1] + '==')
      data = json.loads(body_json)
      print(f"{data['sts:identity_context']}")
      ```

1.  Call the `AssumeRole` API with the extracted `sts:identity_context` and the ISV `tenantId` information. 

   ```
   aws sts assume-role \
         --role-arn ${your_iam_role} \
         --role-session-name test-session \
         --provided-contexts '[{"ProviderArn": "arn:aws:iam::aws:contextProvider/IdentityCenter", "ContextAssertion": "${value from sts:identity_context}"}]' \
         --tags Key=qbusiness-dataaccessor:ExternalId,Value=${isv tenantId}
   ```

    Use the AWS Sig V4 credentials returned from the previous step to call `SearchRelevantContent` API. 

   ```
   aws qbusiness search-relevant-content \
         --application-id ${qbusiness_application_id} \
         --query-text "What is Amazon Q?" \
         --content-source '{"retriever": {"retrieverId": "${retriever_id}"}}'
   ```

------

# Creating an Amazon Q index on behalf of a customer
<a name="isv-creating-index"></a>

We recommend creating one Amazon Q Business application environment per customer for better security and data segregation. Alternatively, you can create one Amazon Q Business application environment and share it with multiple customers. This is only recommended when you index documents that are visible to all users in your application.

**Topics**
+ [Determine the identity management for your customer's Amazon Q Business application](#isv-creating-index-identity-management)
+ [Calling the SearchRelevantContent API to an Amazon Q index with an IAM Identity Center application environment](#isv-calling-api-idc)
+ [Calling the SearchRelevantContent API on an Amazon Q application environment with IAM Federation](#isv-calling-api-iam)

## Determine the identity management for your customer's Amazon Q Business application
<a name="isv-creating-index-identity-management"></a>

All Amazon Q Business application environments require user access through AWS Identity and Access Management (IAM) identity management. You can choose one of two types of user IAM identity management methods supported by Amazon Q Business. These are IAM Identity Center and IAM Federation. Both IAM Identity Center and IAM Federation require an external identity provider setup to allow end users to log in through their identity provider.

IAM Identity Center provides advanced user group management, while Identity and Access Management (IAM) Federation provides more service quotas for the external identity providers. You can choose the identity management that's best suited for you and your end customer when creating their Amazon Q Business application environment. For more information, see [Configuring an Amazon Q Business application environment using AWS IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html) and [Creating an Amazon Q Business application environment using Identity Federation through IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html)

After the Amazon Q Business application environment is created, set up the retriever and connect the data sources. For a complete list of data source connectors,see [supported connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connectors-list.html). You will need your customers to provide the relevant credentials for each connector that you intend to retrieve data from. For more information, see [Creating a retriever for an Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html) and [Connecting Amazon Q Business data sources](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-sources.html).

## Calling the SearchRelevantContent API to an Amazon Q index with an IAM Identity Center application environment
<a name="isv-calling-api-idc"></a>

Before end users can retrieve content from the Amazon Q index that you have been granted access to, you need to be able to make authenticated Amazon Q Business API calls, like the `SearchRelevantContent` API operation.

To do this you, must complete the steps in [Make authenticated Amazon Q Business API calls using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/making-sigv4-authenticated-api-calls.html).

**Note**  
Use the instructions from the previous topic, but modify the `QBusinessConversationPermission` permission by adding the additional action `, "qbusiness:SearchRelevantContent"` to the list of allowed actions, as shown in the following sample snippet of the full permission.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "QBusinessConversationPermission",
            "Effect": "Allow",
            "Action": [
                "qbusiness:Chat",
                "... ",
                "qbusiness:SearchRelevantContent"
            ]
        }
    ]
}
```

------

When configuring access scopes for your Amazon Q Businessapplication environment, add the following using the AWS CLI to enable calling the `SearchRelevantContent` API:

```
    aws sso-admin put-application-access-scope \
    --application-arn identity-center-custom-application-arn \
    --scope "qbusiness:conversations:access"
    
    aws sso-admin put-application-access-scope \
    --application-arn identity-center-custom-application-arn \
    --scope "qbusiness:content:access"
```

The following AWS CLI example shows how to call this `SearchRelevantContent` API operation after you have these credentials.

```
    aws qbusiness search-relevant-content \
      --application-id ${qbusiness_application_id} \
      --query-text "What is Amazon Q?" \
      --content-source '{"retriever": {"retrieverId": "${retriever_id"}}'
```

## Calling the SearchRelevantContent API on an Amazon Q application environment with IAM Federation
<a name="isv-calling-api-iam"></a>

Before end users can retrieve content from the Amazon Q index that you have been granted access to, you need to be able to make authenticated Amazon Q Business API calls, like the `SearchRelevantContent` API operation.

To do this, complete the steps in [Make authenticated Amazon Q Business API calls using IAM federation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/making-sigv4-authenticated-api-calls-iam.html).

**Note**  
Use the instructions in the previous topic, but modify the `trustpolicyforfederation` policy by adding the additional action, `"qbusiness:SearchRelevantContent"` to the list of allowed actions, as shown in the following sample snippet of the full permission.  

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "QBusinessConversationPermissions",
            "Effect": "Allow",
            "Action": [
                "qbusiness:Chat",
                "qbusiness:SearchRelevantContent"
            ],
            "Resource": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
        }
    ]
}
```

The following AWS CLI; example shows how to call this `SearchRelevantContent` API operation after you have these credentials.

```
    aws qbusiness search-relevant-content \
      --application-id ${qbusiness_application_id} \
      --query-text "What is Amazon Q?" \
      --content-source '{"retriever": {"retrieverId": "${retriever_id"}}'
```

# Troubleshooting
<a name="isv-troubleshooting"></a>

If ISVs encounter issues with accessing the Amazon Q index, consider the following.

1. Verify the Identity and Access Management (IAM) role and permissions.

1. Check the configuration of the redirect URL for the oauth flow.

1. Confirm that the customer has granted the necessary access permissions to the ISV.