# Action connectors
<a name="action-integrations"></a>

Action connectors use secure connections to external services and execute actions based on your authentication level and permissions.

# How action connectors work
<a name="int-actions-how-it-works"></a>

Action connectors in Amazon Quick create secure connections between Amazon Quick and external services. When you configure these integrations, you can perform actions based on your authentication level and permissions.

## Core components
<a name="qbs-actions-how-it-works-qbs-actions-core-components"></a>

**Action connectors**  
The foundational resources that integrate with external services. Amazon Quick supports 15 third-party integrations and 5 AWS service integrations. For information about setting up AWS built-in service action connectors, see [AWS service action connectors](builtin-services-integration.md).

**Authentication methods**  
Action connectors support multiple authentication methods including managed (3LO), custom user-based, API key, and 2LO. For detailed information about each authentication method, see [Authentication methods](action-connector-apis.md#action-connector-apis-authentication).

**Implementation types**  
+ **On-demand actions for immediate, user-triggered operations** - Real-time operations that execute immediately when you trigger them. You can initiate actions through chat interfaces, dashboards, or Amazon Q Apps. Examples include creating tickets, sending messages, or querying data.
+ **Automated workflows for scheduled or system-triggered tasks** - System-managed operations that execute based on schedules or triggers. They run in the background without user intervention. Examples include data synchronization, report generation, or system maintenance.

**Permission models**  
+ **Personal access permissions through 3LO** - You can grant specific permissions to Amazon Quick through Three-Legged OAuth, maintaining control over your service access. Permissions are tied to your identity and credentials in the target service.
+ **Service-level permissions for automated workflows** - Applied to automated workflows, these permissions support system-to-system interactions without user involvement. They're configured at the service level and typically use API keys or service account credentials.
+ **Entity-level access controls** - Govern access to actions within Amazon Quick, determining which users or groups can execute specific actions. These controls integrate with Amazon Quick's broader permission system for consistent access management across the platform.

# Types of actions
<a name="int-actions-types"></a>

Amazon Quick supports two methods of invoking actions, each serving different use cases and authentication models.

## On-demand actions
<a name="qbs-actions-types-qbs-actions-on-demand"></a>

On-demand actions execute immediately when you trigger them. These actions support interactive operations that require real-time response.

**Key characteristics:**
+ User-initiated execution - You trigger actions through natural language in the chat interface.
+ Interactive form completion - You fill out forms with required parameters before the action executes.
+ Immediate response - Actions execute in real-time and provide instant feedback on success or failure.
+ Personal authentication (3LO) - Uses your individual credentials and permissions from the target service.

**Common use cases:**
+ Creating tickets in Jira.
+ Sending messages in Slack.
+ Updating Salesforce records.
+ Retrieving information from SharePoint.

## Automated workflows
<a name="qbs-actions-types-qbs-actions-automated-workflows"></a>

Automated workflows execute actions on a schedule or in response to specific triggers. These are useful for background and system-level operations.

**Key characteristics:**
+ System-level execution - Actions run automatically without user intervention based on predefined triggers.
+ Scheduled or event-triggered - Execute on time-based schedules or in response to specific system events.
+ Non-interactive operation - Run in the background without requiring user input or form completion.
+ Service-level authentication - Use system credentials rather than individual user authentication.

**Common use cases:**
+ Regular data synchronization.
+ Scheduled report generation.
+ Automated ticket updates.
+ System health checks.

# Bounded and unbounded agents
<a name="int-actions-bounded-unbounded"></a>

Amazon Quick offers two types of agents that provide different levels of access and functionality: bounded and unbounded agents. Understanding the differences between these agent types helps you implement the right solution for your use case.

## Bounded agents
<a name="qbs-actions-bounded-unbounded-qbs-actions-bounded-agents"></a>

Bounded agents operate within defined parameters, specifically linked to one or more spaces within Amazon Quick. These agents can only access and perform actions on resources that are explicitly connected to their assigned spaces. For example, a bounded agent configured for the HR space can only access HR-related documents, datasets, and execute HR-related actions.

Use bounded agents for:
+ Department-specific workflows (HR, Finance, IT).
+ Project team collaborations.
+ Sensitive data handling.
+ Compliance-focused operations.

The bounded nature provides enhanced security by ensuring the agent can't access resources outside its designated spaces. This makes it ideal for scenarios where data isolation is important.

## Unbounded agents
<a name="qbs-actions-bounded-unbounded-qbs-actions-unbounded-agents"></a>

Unbounded agents have broader access capabilities and can work across all configured actions and resources within the Amazon Quick environment. These agents aren't restricted to specific spaces and can access any properly configured action connector available in the system.

Use unbounded agents for:
+ Organization-wide assistance.
+ Cross-departmental workflows.
+ General-purpose actions.
+ Scenarios requiring access to multiple systems.

# Prerequisites
<a name="int-actions-prerequisites"></a>

Before using actions in Amazon Quick, ensure you have the following:

## License requirements
<a name="qbs-actions-prerequisites-qbs-actions-license-requirements"></a>

One of the following Amazon Quick licenses:
+ Reader Pro - Provides read access to data and the ability to execute actions in connected services.
+ Author - Includes Reader Pro capabilities plus the ability to create and modify content and configurations.
+ Author Pro - Full feature access including advanced action configuration and administrative capabilities.

## Service requirements
<a name="qbs-actions-prerequisites-qbs-actions-service-requirements"></a>

For third-party services (such as Jira or Salesforce), ensure that you have:
+ Appropriate permissions in the target services.
+ Authentication credentials for each service.

For AWS action connectors, you need admin access to the relevant services.

## AWS account requirements
<a name="qbs-actions-prerequisites-qbs-actions-aws-account-requirements"></a>
+ Active AWS account - A valid AWS account with billing enabled and in good standing.
+ Appropriate IAM permissions - IAM roles and policies that allow Amazon Quick to access the required AWS services.
+ Required service quotas - Sufficient service limits for the AWS services you plan to integrate with your actions.

# Supported action connector types and available actions
<a name="action-connector-apis-supported-types"></a>

Amazon Quick supports multiple connector types, each with specific actions available:

## External service connectors
<a name="action-connector-apis-external-services"></a>
+ **Salesforce** - Create records, update opportunities, search accounts, manage leads.
+ **JIRA** - Create issues, update tickets, search projects, manage workflows.
+ **Microsoft Outlook** - Send emails, manage calendar events, access contacts.
+ **Slack** - Send messages, create channels, manage notifications.
+ **ServiceNow** - Create incidents, update requests, manage workflows.
+ **Zendesk** - Create tickets, update cases, search knowledge base.
+ **PagerDuty** - Create incidents, manage escalations, update on-call schedules.
+ **Asana** - Create actions, update projects, manage team workflows.
+ **BambooHR** - Access employee data, manage time-off requests.
+ **Box** - Manage files, folders, and collaborate on documents.
+ **Canva** - Create and edit designs, manage templates and assets.
+ **FactSet** - Access financial data, generate reports.
+ **GitHub** - Manage repositories, issues, pull requests, and code collaboration.
+ **HuggingFace** - Access AI models, datasets, and machine learning workflows.
+ **HubSpot** - Manage contacts, deals, marketing campaigns, and CRM data.
+ **Intercom** - Manage customer conversations, support tickets, and messaging.
+ **Linear** - Create and manage issues, projects, and development workflows.
+ **Monday** - Manage projects, tasks, and team collaboration workflows.
+ **Notion** - Create and manage pages, databases, and collaborative workspaces.
+ **Smartsheet** - Update sheets, manage project data.
+ **Confluence** - Create, update, and manage pages, spaces, and other Confluence objects.
+ **SharePoint** - Perform actions on SharePoint lists, items, and Excel files with 19 available actions for creating, updating, deleting, and retrieving SharePoint content.
+ **OneDrive** - Create, update, delete, and manage OneDrive files and folders.
+ **SAP** - Access SAP S/4HANA systems to perform Read only operation on enterprise data.

## AWS service connectors
<a name="action-connector-apis-aws-services"></a>
+ **Amazon S3** - Upload files, manage buckets, retrieve objects.
+ **Amazon Bedrock** - Generate content, analyze data, process requests.
+ **Amazon Textract** - Extract text and data from documents.
+ **Amazon Comprehend** - Natural language processing and sentiment analysis.
+ **Amazon Comprehend Medical** - Medical text analysis and entity extraction.

## Action connector compatibility matrix
<a name="action-connector-compatibility-matrix"></a>

The following table shows which Amazon Quick features each action connector type supports:


**Action Connector Feature Compatibility**  

| Action Connector | Chat Agents | Flows | Dashboard Visuals | Dashboard Alerts | Automations | Companions | 
| --- | --- | --- | --- | --- | --- | --- | 
| AWS Built-in Services | 
| AWS Bedrock Agent Runtime | — | — | — | — | ✓ | — | 
| AWS Bedrock Data Automation Runtime | — | — | — | — | ✓ | — | 
| AWS Bedrock Runtime | — | — | — | — | ✓ | — | 
| Amazon Comprehend | — | — | — | — | ✓ | — | 
| Amazon Comprehend Medical | — | — | — | — | — | — | 
| Amazon S3 | — | — | — | — | ✓ | — | 
| Amazon Textract | — | — | — | — | ✓ | — | 
| External Service Connectors | 
| Asana | ✓ | ✓ | — | — | — | ✓ | 
| Atlassian Confluence Cloud | ✓ | ✓ | — | — | ✓ | ✓ | 
| Atlassian Jira Cloud | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| BambooHR | ✓ | ✓ | — | — | — | ✓ | 
| Box | ✓ | ✓ | — | — | — | — | 
| Canva | ✓ | ✓ | — | — | — | — | 
| FactSet | ✓ | ✓ | — | — | — | — | 
| GitHub | ✓ | ✓ | — | — | — | — | 
| HuggingFace | ✓ | ✓ | — | — | — | — | 
| HubSpot | ✓ | ✓ | — | — | — | — | 
| Intercom | ✓ | ✓ | — | — | — | — | 
| Linear | ✓ | ✓ | — | — | — | — | 
| Monday | ✓ | ✓ | — | — | — | — | 
| Notion | ✓ | ✓ | — | — | — | — | 
| Microsoft OneDrive | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Outlook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Microsoft SharePoint | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Teams | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| PagerDuty | ✓ | ✓ | — | — | ✓ | ✓ | 
| Salesforce | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| SAP | ✓ | — | — | — | ✓ | ✓ | 
| ServiceNow | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Slack | ✓ | ✓ | ✓ | — | — | ✓ | 
| Smartsheet | ✓ | ✓ | — | — | — | ✓ | 
| Zendesk | ✓ | ✓ | — | — | — | ✓ | 
| Custom Connector Types | 
| Model Context Protocol (MCP) | ✓ | ✓ | — | — | ✓ | — | 
| OpenAPI | ✓ | ✓ | — | — | — | — | 
| REST API | — | — | — | — | ✓ | — | 

**Authentication Support:**
+ **Chat Agents and Companions** - Support user authentication (3LO, Basic)
+ **Dashboard Visuals** - Support user authentication (3LO)
+ **Dashboard Alerts** - Support system authentication (2LO or API Key)
+ **Automations** - Support system authentication (2LO)

# Action connector APIs
<a name="action-connector-apis"></a>

Action connector APIs let you programmatically create and manage connections between Amazon Quick and external services. These APIs support the action integration functionality that allows users to perform actions in third-party applications directly from Amazon Quick chat interfaces and automated workflows.

## What are action connector APIs?
<a name="action-connector-apis-overview"></a>

Action connectors serve as the foundational resources that enable integration with first and third party applications. Through these APIs, you can authenticate to applications, manage permissions, and control which actions are available to users within your Amazon Quick applications.

### How action connector APIs support action integrations
<a name="action-connector-apis-task-integrations"></a>

Action connector APIs provide the backend infrastructure for Amazon Quick action integrations. When you create an action connector through the API, you establish a secure connection that lets you:
+ Execute actions in external services through chat interfaces.
+ Perform automated workflows in background processes.
+ Integrate third-party services with Amazon Quick applications.
+ Manage authentication and permissions for service access.

The APIs handle the complex authentication flows, credential management, and permission controls needed to securely connect Amazon Quick with external services.

## Authentication methods
<a name="action-connector-apis-authentication"></a>

Action connector APIs support multiple authentication methods to accommodate different use cases and security requirements:

### Managed authentication (3LO)
<a name="qbs-action-connector-apis-managed-auth"></a>

Three-Legged OAuth provides the simplest setup for personal access to third-party services:
+ No initial configuration required.
+ User-specific authentication through service provider login.
+ Automatic token refresh with 90-day lifecycle.
+ Secure credential storage managed by Amazon Quick.

### Service-to-service authentication (2LO)
<a name="qbs-action-connector-apis-service-auth"></a>

For complex enterprise integrations:
+ Supports client credentials OAuth flow.
+ Enables system-to-system interactions.
+ Requires client ID, client secret, and token URL configuration.
+ Suitable for automated workflows requiring sophisticated security.
+ OAuth - Dynamic Client Registration (DCR - applicable only for select MCP servers).

### API key authentication
<a name="qbs-action-connector-apis-api-key"></a>

Simplified authentication for automated workflows:
+ Single token-based authentication.
+ Service-level permissions.
+ Ideal for background processes and scheduled actions.
+ Requires valid API key from target service.

### Basic Auth
<a name="qbs-action-connector-apis-basic-auth"></a>

Basic authentication provides a simple username/password authentication method:
+ Uses standard HTTP Basic Authentication headers.
+ Credentials are base64 encoded.
+ Suitable for services that don't support OAuth or API keys.
+ Requires secure HTTPS connection.
+ Not recommended for public-facing services.

### None
<a name="qbs-action-connector-apis-no-auth"></a>

No authentication required:
+ Used for public APIs and services.
+ No credentials or tokens needed.
+ Limited to read-only or public operations.
+ Typically used for public data feeds and documentation.
+ Should not be used for sensitive operations.

## Permissions and access control
<a name="qbs-action-connector-apis-permissions"></a>

Action connector APIs implement comprehensive permission controls through Access Control Lists (ACLs):

### Resource-level permissions
<a name="qbs-action-connector-apis-resource-permissions"></a>
+ **Owner** - Full control including delete and permission management.
+ **Contributor** - Can use and modify connector settings.
+ **Viewer** - Can view connector details and use enabled actions.

### API operations for permission management
<a name="qbs-action-connector-apis-permission-operations"></a>
+ `DescribeActionConnectorPermissions` - Retrieve current permission settings.
+ `UpdateActionConnectorPermissions` - Grant or revoke user permissions.

## Supported connector categories
<a name="qbs-action-connector-apis-categories"></a>

### Dual-purpose connectors
<a name="qbs-action-connector-apis-dual-purpose"></a>

These connectors support both action integrations and knowledge base creation:
+ **Amazon S3** - Use the Admin Console to create Actions for file operations, use the webapp to create knowledge bases from S3 content.
+ **Microsoft SharePoint** - Document management actions, content indexing.
+ **OneDrive** - File operations, document search capabilities.
+ **Confluence** - Content creation actions, knowledge base integration.

### Action-only connectors
<a name="qbs-action-connector-apis-task-only"></a>

Specialized for action execution without knowledge base capabilities:
+ **Salesforce** - Enterprise CRM integration supporting account and contact operations, custom object CRUD operations, Sales process automation.
+ **JIRA** - Issue tracking and project management.
+ **Microsoft Outlook** - Send emails, manage calendar events, access contacts.
+ **Slack** - Communication and notification workflows.
+ **ServiceNow** - IT service management operations.
+ **Zendesk** - Create tickets, update cases, search knowledge base.
+ **PagerDuty** - Create incidents, manage escalations, update on-call schedules.
+ **Asana** - Create actions, update projects, manage team workflows.
+ **BambooHR** - Access employee data, manage time-off requests.
+ **Smartsheet** - Update sheets, manage project data.
+ **FactSet** - Access financial data, generate reports.
+ **SAP** - Access SAP systems, execute business functions, and manage enterprise data.

### Knowledge base-only connectors
<a name="qbs-action-connector-apis-data-only"></a>

Focused on knowledge base integration without action capabilities:
+ **Google Drive** - Document indexing and search.
+ **Web Crawler** - Content discovery and indexing.

## API lifecycle management
<a name="qbs-action-connector-apis-lifecycle"></a>

### Credential management
<a name="qbs-action-connector-apis-credential-management"></a>
+ Automatic refresh token handling for OAuth action connectors.
+ Secure storage of authentication credentials using AWS KMS.
+ Support for credential rotation and updates.
+ Cross-account access for Amazon S3 connectors.

### Connection updates
<a name="qbs-action-connector-apis-connection-updates"></a>

Use the `UpdateActionConnector` API to:
+ Modify authentication credentials.
+ Update service configuration parameters.
+ Change action connector metadata.

### Monitoring and troubleshooting
<a name="qbs-action-connector-apis-monitoring"></a>
+ Track API usage through CloudWatch metrics.
+ Monitor connection health and authentication status.
+ Implement error handling for common failure scenarios.
+ Use validation APIs to diagnose configuration issues.

## Rate limiting and quotas
<a name="qbs-action-connector-apis-rate-limiting"></a>

Action connector APIs implement standard AWS API rate limiting:
+ Standard AWS API throttling applies to all operations.
+ Connection validation may have additional limits.
+ Action execution rates depend on target service capabilities.
+ Implement exponential backoff for retry logic.

## Cross-account support
<a name="qbs-action-connector-apis-cross-account"></a>

For Amazon S3 connectors, the APIs support cross-account access:
+ Specify different AWS account IDs during connector creation.
+ Configure appropriate IAM permissions for cross-account access.
+ Use AWS KMS for secure credential management across accounts.
+ Validate permissions before enabling cross-account connections.

## Error handling and troubleshooting
<a name="qbs-action-connector-apis-error-handling"></a>

Action connector APIs return standard AWS error responses:

### Common error types
<a name="qbs-action-connector-apis-common-errors"></a>
+ `AccessDeniedException` - Insufficient permissions for the operation.
+ `InvalidParameterValueException` - One or more parameter values are invalid for the operation.
+ Invalid configuration parameters - Service-specific configuration values are incorrect or missing.
+ `ResourceNotFoundException` - Connector or resource not found.
+ `ThrottlingException` - Rate limit exceeded.
+ `ConflictException` - Resource conflict or duplicate names.
+ `InternalFailureException` - Internal service error occurred during request processing.
+ `ResourceExistsException` - Attempt to create a resource that already exists.
+ `InvalidNextTokenException` - The pagination token provided is invalid or expired.
+ `AccessTokenNotFoundException` - User needs to authorize the connection (that is, sign-button). This exception is used by UX to ask users for authorization.
+ `TokenResponseException` - Action setup is not valid.

Implement proper error handling in your applications to manage these scenarios gracefully and provide meaningful feedback to users.

## Using Action Connector APIs with AWS CLI
<a name="qbs-action-connector-apis-cli-examples"></a>

You can use the AWS CLI to manage action connectors programmatically. The following examples demonstrate common operations using generic placeholder values.

### Creating an action connector
<a name="create-action-connector-cli"></a>

Use the `create-action-connector` command to create a new action connector for integrating with external services.

```
aws quicksight create-action-connector \
  --aws-account-id "123456789012" \
  --name "MyS3Connector" \
  --action-connector-id "my-s3-connector-id" \
  --type "AMAZON_S3" \
  --authentication-config '{
    "AuthenticationType": "IAM",
    "AuthenticationMetadata": {
      "IamConnectionMetadata": {
        "RoleArn": "arn:aws:iam::123456789012:role/MyConnectorRole"
      }
    }
  }' \
  --enabled-actions "CreateBucket" "ListBuckets" \
  --description "S3 connector for automation workflows" \
  --region "us-east-1"
```

### Listing action connectors
<a name="list-action-connectors-cli"></a>

Use the `list-action-connectors` command to retrieve all action connectors in your account.

```
aws quicksight list-action-connectors \
  --aws-account-id "123456789012" \
  --max-results 10 \
  --region "us-east-1"
```

### Describing an action connector
<a name="describe-action-connector-cli"></a>

Use the `describe-action-connector` command to get detailed information about a specific action connector.

```
aws quicksight describe-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

### Updating an action connector
<a name="update-action-connector-cli"></a>

Use the `update-action-connector` command to modify an existing action connector's configuration.

```
aws quicksight update-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --name "UpdatedS3Connector" \
  --authentication-config '{
    "AuthenticationType": "IAM",
    "AuthenticationMetadata": {
      "IamConnectionMetadata": {
        "RoleArn": "arn:aws:iam::123456789012:role/UpdatedConnectorRole"
      }
    }
  }' \
  --enabled-actions "CreateBucket" "ListBuckets" "DeleteBucket" \
  --region "us-east-1"
```

### Searching action connectors
<a name="search-action-connectors-cli"></a>

Use the `search-action-connectors` command to find action connectors based on specific criteria.

```
aws quicksight search-action-connectors \
  --aws-account-id "123456789012" \
  --max-results 5 \
  --filters '[{
    "Name": "ACTION_CONNECTOR_NAME",
    "Operator": "StringLike",
    "Value": "S3"
  }]' \
  --region "us-east-1"
```

### Managing action connector permissions
<a name="update-action-connector-permissions-cli"></a>

Use the `update-action-connector-permissions` command to grant or revoke permissions for an action connector.

```
aws quicksight update-action-connector-permissions \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --grant-permissions '[{
    "Actions": [
      "quicksight:DescribeActionConnector",
      "quicksight:UpdateActionConnector",
      "quicksight:DeleteActionConnector"
    ],
    "Principal": "arn:aws:quicksight:us-east-1:123456789012:user/default/myuser"
  }]' \
  --region "us-east-1"
```

### Viewing action connector permissions
<a name="describe-action-connector-permissions-cli"></a>

Use the `describe-action-connector-permissions` command to view current permissions for an action connector.

```
aws quicksight describe-action-connector-permissions \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

### Deleting an action connector
<a name="delete-action-connector-cli"></a>

Use the `delete-action-connector` command to remove an action connector from your account.

```
aws quicksight delete-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

## Next steps
<a name="qbs-action-connector-apis-next-steps"></a>

After understanding action connector APIs, you can:
+ Review the complete API reference documentation for detailed parameter specifications.
+ Explore specific connector setup guides for your target services.
+ Implement authentication flows appropriate for your use case.
+ Set up monitoring and error handling for production deployments.
+ Configure permissions and access controls for your organization.

# Authentication methods
<a name="quick-action-auth"></a>

Amazon Quick supports multiple authentication methods, each designed for specific use cases and security requirements.

## Managed authentication (3LO)
<a name="quick-managed-auth"></a>

Three-Legged OAuth (3LO) is the recommended authentication method for personal access to third-party services.

**Key features of 3LO:**
+ No initial configuration required.
+ User-specific authentication.
+ Secure credential storage.
+ Automatic token refresh.
+ 90-day refresh token lifecycle.

**3LO setup process:**

1. Select connector.

1. Choose managed authentication.

1. Complete service provider login.

1. Grant requested permissions.

1. Confirm connection.

## Custom user-based authentication
<a name="quick-custom-user-auth"></a>

For scenarios that require specific organizational control or custom configuration.

**Required information:**
+ Client ID.
+ Client Secret.
+ Domain URL.
+ Authorization URL.
+ Token URL.
+ Redirect URL.

**Configuration steps:**

1. Obtain credentials from service provider.

1. Configure authentication settings.

1. Validate connection.

1. Test access permissions.

When configuring user-based authentication in the Amazon Quick console, obtain the proper credentials from your service provider and configure your authentication settings. Then validate the connection and test your access permissions.

## API key authentication
<a name="quick-actions-api-key-auth"></a>

Used primarily for automated workflows and system-level access.

**Key features:**
+ Simple token-based authentication.
+ Single credential management.
+ Service-level permissions.
+ Suitable for automated processes.

**Setup requirements:**

When setting up API Key authentication, ensure that you have the following:
+ Valid API key from service.
+ Appropriate service permissions.
+ Secret storage configuration.

## Service-to-service authentication
<a name="quick-actions-service-to-service-auth"></a>

For automated workflows that require complex authentication.

**Configuration requirements:**
+ Client ID.
+ Client Secret.
+ Domain URL.
+ Token URL.
+ Service-specific parameters.

# Action execution methods
<a name="int-actions-execution"></a>

Amazon Quick provides multiple ways to execute actions, accommodating different use cases and interaction preferences.

## Chat interface
<a name="qbs-actions-execution-qbs-actions-chat-interface"></a>

You can execute implicit actions in the Amazon Quick chat.

### Implicit actions
<a name="qbs-actions-execution-qbs-actions-implicit-actions"></a>

Amazon Quick also supports implicit action execution through natural conversation with agents. Using advanced natural language processing, the system can identify when your conversation indicates the need for specific actions. Conversations are analyzed to determine which actions are required to fulfill your request.

A single request might require multiple actions to complete. When this happens, the system handles these actions sequentially, guiding you through each step. For each identified action, the system presents the appropriate form for you to complete. After each action completes, you receive a confirmation before moving on to the next action in the sequence.

For example, if you ask "Create a Jira ticket for this issue and notify the team in Slack," the system would:

1. First present the Jira ticket creation form.

1. After completing the ticket creation, show the Slack message form.

1. Complete both actions in sequence.

Throughout the process, you can track your progress through multiple actions. When all actions complete, the system provides a comprehensive summary showing all executed actions and their outcomes. You can access related documentation if needed and review any error states that may have occurred during the process.

# Monitoring and maintenance
<a name="int-actions-monitoring"></a>

Monitoring your action connectors helps ensure reliable performance and identify issues before they impact users. Regular monitoring allows you to track usage patterns, optimize performance, and maintain healthy connections to external services.

## Performance monitoring
<a name="qbs-actions-monitoring-qbs-actions-performance-monitoring"></a>

You can assess action connector performance using the following metrics and analytics.

### CloudWatch metrics
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics"></a>
+ Action execution success rates - Track the percentage of successful action executions to identify reliability issues.
+ Response times - Monitor how long actions take to complete and identify performance bottlenecks.
+ Error frequencies - Track error patterns to identify common failure points and areas for improvement.
+ API quota usage - Monitor usage against service limits to prevent throttling and plan for capacity.

### Usage analytics
<a name="qbs-actions-monitoring-qbs-actions-usage-analytics"></a>

The following usage analytics are collected for action connectors:
+ Active users - Track how many users are actively using action connectors to understand adoption and usage patterns.
+ Popular actions - Identify which actions are used most frequently to prioritize optimization efforts.
+ Execution patterns - Analyze when and how often actions are executed to optimize resource allocation.
+ Error trends - Monitor error patterns over time to identify systemic issues and improvement opportunities.

## Connection health
<a name="qbs-actions-monitoring-qbs-actions-connection-health"></a>

You can assess action connector health using the following connection health tools:

### Status monitoring
<a name="qbs-actions-monitoring-qbs-actions-status-monitoring"></a>
+ Connection state - Monitor whether connectors are actively connected and functioning properly.
+ Authentication validity - Track the status of authentication tokens and credentials to prevent access failures.
+ Token expiration tracking - Monitor when authentication tokens will expire and need renewal.
+ Service availability - Track the availability and response status of connected external services.

### Automated maintenance
<a name="qbs-actions-monitoring-qbs-actions-automated-maintenance"></a>
+ Token refresh handling.
+ Connection recovery.
+ Error retry logic.
+ Performance optimization.

## CloudWatch metrics reference
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics-table"></a>


**Available CloudWatch metrics**  

| Metric | Description | Unit | 
| --- | --- | --- | 
| ActionSuccess | Successful executions | Count | 
| ActionLatency | Execution time | Milliseconds | 
| AuthFailures | Failed authentications | Count | 
| APIThrottling | API throttling events | Count | 

# Best practices
<a name="int-actions-best-practices"></a>

Following best practices for action connectors helps ensure secure, reliable, and efficient operations. These practices help you maintain optimal performance, protect sensitive data, and minimize operational issues.

## Security
<a name="qbs-actions-best-practices-qbs-actions-security-best-practices"></a>

### Authentication management
<a name="qbs-actions-best-practices-qbs-actions-authentication-management"></a>
+ Regular credential rotation - Update API keys and OAuth tokens on a scheduled basis to maintain security.
+ Periodic permission reviews - Audit user and service permissions quarterly to ensure least-privilege access.
+ Token lifecycle monitoring - Track token expiration dates and set up alerts before credentials expire.
+ Access audit logging - Enable comprehensive logging to track who accessed which services and when.

### Access control
<a name="qbs-actions-best-practices-qbs-actions-access-control"></a>
+ Implement least-privilege access - Grant only the minimum permissions necessary for each action to function properly.
+ Regular permission audits - Review and validate that current permissions align with actual usage patterns and business needs.
+ Document access patterns - Maintain clear documentation of who has access to which connectors and why.
+ Monitor usage anomalies - Set up alerts for unusual access patterns that might indicate security issues.

## Performance
<a name="qbs-actions-best-practices-qbs-actions-performance-best-practices"></a>

### Action configuration
<a name="qbs-actions-best-practices-qbs-actions-action-configuration"></a>
+ Optimize form defaults - Pre-populate commonly used values to reduce user input time and errors.
+ Configure appropriate timeouts - Set realistic timeout values based on typical response times for each service.
+ Set up error handling - Implement robust error handling with clear user messages and retry logic where appropriate.
+ Document dependencies - Clearly document any prerequisites or dependencies between different actions.

### Resource management
<a name="qbs-actions-best-practices-qbs-actions-resource-management"></a>
+ Monitor API quotas.
+ Track usage patterns.
+ Optimize refresh schedules.
+ Regular cleanup of unused connectors.

## Maintenance
<a name="qbs-actions-best-practices-qbs-actions-maintenance-best-practices"></a>

### Regular actions
<a name="qbs-actions-best-practices-qbs-actions-regular-tasks"></a>
+ Review connector status.
+ Update configurations.
+ Validate connections.
+ Document changes.

### Troubleshooting
<a name="qbs-actions-best-practices-qbs-actions-troubleshooting-tasks"></a>
+ Monitor error patterns.
+ Review CloudWatch logs.
+ Track resolution times.
+ Document solutions.

# Troubleshooting
<a name="int-actions-troubleshooting"></a>

When action connectors encounter issues, systematic troubleshooting helps you quickly identify and resolve problems. This guidance covers common issues and their solutions to minimize downtime and restore functionality.

## Common issues and solutions
<a name="qbs-actions-troubleshooting-qbs-actions-common-issues"></a>

### Authentication problems
<a name="qbs-actions-troubleshooting-qbs-actions-authentication-problems"></a>

#### Token expiration
<a name="qbs-actions-troubleshooting-qbs-actions-token-expiration"></a>

```
Symptom: "Authentication token expired" error
Resolution:
```

1. Choose "Reconnect" in console.

1. Complete authentication flow.

1. Retry action.

#### Permission errors
<a name="qbs-actions-troubleshooting-qbs-actions-permission-errors"></a>

```
Symptom: "Insufficient permissions" message
Resolution:
```

1. Verify service permissions.

1. Check connector configuration.

1. Review action requirements.

#### Connection failures
<a name="qbs-actions-troubleshooting-qbs-actions-connection-failures"></a>

```
Symptom: "Unable to connect to service" error
Resolution:
```

1. Verify service availability.

1. Check network connectivity.

1. Validate credentials.

1. Review service quotas.

### Action-specific issues
<a name="qbs-actions-troubleshooting-qbs-actions-action-specific-issues"></a>

#### Form submission failures
<a name="qbs-actions-troubleshooting-qbs-actions-form-submission-failures"></a>

##### Validation errors
<a name="qbs-actions-troubleshooting-qbs-actions-validation-errors"></a>
+ Check required fields.
+ Verify data formats.
+ Review field limitations.
+ Check for special characters.

##### Timeout issues
<a name="qbs-actions-troubleshooting-qbs-actions-timeout-issues"></a>
+ Reduce form complexity.
+ Check network latency.
+ Review service response times.
+ Consider breaking into multiple actions.

#### Sync and performance issues
<a name="qbs-actions-troubleshooting-qbs-actions-sync-performance-issues"></a>

##### Slow response times
<a name="qbs-actions-troubleshooting-qbs-actions-slow-response-times"></a>

```
Resolution:
```

1. Check API rate limits.

1. Review concurrent executions.

1. Monitor service health.

1. Optimize action configuration.

##### Failed executions
<a name="qbs-actions-troubleshooting-qbs-actions-failed-executions"></a>

```
Resolution:
```

1. Review CloudWatch logs.

1. Check error messages.

1. Verify service status.

1. Test connection health.

## Common error messages
<a name="qbs-actions-troubleshooting-qbs-actions-error-messages"></a>


**Error codes and resolutions**  

| Error code | Description | Resolution | 
| --- | --- | --- | 
| AUTH\$1001 | Authentication failed | Verify credentials and retry | 
| CONN\$1002 | Connection timeout | Check network and service status | 
| PERM\$1003 | Insufficient permissions | Review required permissions | 
| TOKEN\$1004 | Token expired | Reinitiate authentication |