AWS Builder Center

Builder Center

Build a Custom Action Connector in Amazon Quick using the OpenAPI specification

Learn how to build a custom action connector in Amazon Quick by importing an OpenAPI specification. This guide walks through how Quick turns a spec into callable actions, the end-to-end setup workflow, and how the OpenAPI security scheme (oauth2, apiKey, http/bearer) controls authentication. Includes a complete example spec, the exact fields each auth type asks for, and some common pitfalls.

Jed Lechner

Amazon Quick  is an agentic AI workspace that lets teams automate tasks, conduct research, and work with their data through conversational AI. Much of that value comes from action connectors : integrations that let Quick call APIs from chat agents, automations, or apps, and take actions in the systems your team already uses. Quick ships with built-in connectors for many services like Microsoft, Google, Salesforce, ServiceNow, Jira, and GitHub. When you need one that doesn't exist yet, or you want to customize a built-in connector, you can configure a custom integration through a Model Context Protocol (MCP) server  or an OpenAPI Specification .
In this post, we cover how the OpenAPI specification integration turns a spec into callable actions, how to set one up end to end in the Amazon Quick console, and how the security scheme in your spec shapes authentication.

How the OpenAPI integration works

An OpenAPI specification is a machine-readable description of an API, written in JSON, following the OpenAPI Specification standard . It lists the API's paths, the operations on each path, the parameters each operation takes, the shape of the responses, and how the API authenticates.
Here is a complete, minimal spec with one operation:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
"openapi": "3.0.1",
"info": {
"title": "Example API",
"description": "A small example API used to build a Quick connector.",
"version": "1.0"
},
"servers": [
{ "url": "https://api.example.com" }
],
"security": [
{ "ApiKeyAuth": [] }
],
"paths": {
"/user": {
"get": {
"operationId": "GetCurrentUser",
"summary": "Get the current user",
"description": "Returns the profile of the account that owns the API key. Use this to confirm who the request is authenticated as.",
"responses": {
"200": {
"description": "The user profile was returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "integer", "description": "Numeric account identifier." },
"username": { "type": "string", "description": "The account's login handle." }
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "API key sent in the X-API-Key header."
}
}
}
}
When you import a spec like the one above, Quick reads it and generates one action per operation. Each action becomes a tool an agent, flow, or app can call. The example spec has a single operation, so it produces a single action. Three parts of each operation determine how its action behaves:
  • operationId becomes the action's name. The "operationId": "GetCurrentUser" in the spec above becomes an action named GetCurrentUser.
  • The operation description is what the agent reads to decide when to call the action, so it does more than document the API. Quick requires a description on every operation and every parameter, and how clearly you write it affects whether the agent picks the right action for a request.
  • The HTTP method sets whether the action is a read or a write. GET operations default to read, everything else defaults to write. You can override this with the x-amzn-operation-type extension when the default is wrong for a given operation.
The result is that a spec with, say, four operations becomes a connector with four actions, each named, described, and typed as read or write, ready for an agent to call.

Setting up the integration

To configure your integration in your Amazon Quick console:
  1. Go to Connectors, choose the Create for your team tab, and choose OpenAPI Specification. If you already have an OpenAPI connector, Quick asks whether you want an existing one or a new one; choose to create new.
  2. On the Add schema step, choose Import Schema and upload your JSON spec. Quick validates it in place and reports errors in the editor. You cannot advance until it reports zero errors.
  3. On the Create step, name the connector, give it a description, and configure how Quick authenticates to the API. This is where the security scheme in your spec decides what you are asked for, covered in the next section.
  4. Review the generated actions. Each operation from your spec appears here as a named action with its read or write type.
  5. Choose who to share the connector with, then publish. You do not have to share it; a connector can stay visible only to you, which is a good way to test each operation before anyone else uses it. When you do share, consider publishing an agent, skill, or usage guide alongside it for the people who will use the connector.
  6. Open the published connector and use Test action APIs to run an operation and confirm it works end to end.

Authentication

Authentication is a step in that setup flow, and the user interface options are shaped by your spec. The securitySchemes block, inside components, declares how the API authenticates. You reference a scheme by name in the top-level security field to apply it to every operation. Quick reads the scheme's type and uses it to decide which credential fields the Create step in the Quick console shows you and how it attaches credentials to every outbound request.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"openapi": "3.0.1",
"info": { "title": "My API", "version": "1.0" },
"servers": [ { "url": "https://api.example.com" } ],
"security": [
{ "MyScheme": [] }
],
"paths": { ... },
"components": {
"securitySchemes": {
"MyScheme": {
"type": "...",
"...": "scheme-specific fields"
}
}
}
}
Below are some common security schema types and their corresponding behaviors in Amazon Quick during configuration.

oauth2

Declaring type: oauth2 tells Quick to run an OAuth 2.0 flow. What matters here is the flow key you declare inside flows, not the URL values you put in it. Quick reads the flow key to decide which authentication form to show. Declare authorizationCode when each user signs in individually, or clientCredentials when one service credential covers all calls.
1
2
3
4
5
6
7
8
9
10
11
12
"securitySchemes": {
"OAuth2": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://example.com/oauth/authorize",
"tokenUrl": "https://example.com/oauth/token",
"scopes": { "read": "Read access", "write": "Write access" }
}
}
}
}
At the Create step, the flow key determines the Auth configuration and the fields you fill in. An authorizationCode flow presets Auth configuration to Custom OAuth app and asks for Base URL, Client ID, Client secret, Token URL, and Authorization URL, plus a Public OAuth client checkbox. A clientCredentials flow presets it to Service-to-Service OAuth and asks for Base URL, Client ID, Client secret, and Token URL only, with no Authorization URL because there is no user sign-in step.
The URL values you write in the scheme are not carried into the connector. Quick reads the flow key, but the authorizationUrl and tokenUrl strings in the spec are ignored at setup; you enter the actual URLs into the form yourself. The one field Quick fills in is the Redirect URL, which it generates as your account's OAuth callback endpoint (https://{region}.quicksight.aws.amazon.com/sn/oauthcallback) and locks. That is the value you register back in the provider's OAuth application so the sign-in flow returns to Quick. Because the values are ignored, a clientCredentials scheme that omits authorizationUrl imports without error, matching the OpenAPI standard, which does not use an authorization URL for that flow.

apiKey

Declaring type: apiKey tells Quick to collect a single credential and send it on every request. The in field says whether it goes in a header or query parameter, and name gives the exact header or parameter name.
1
2
3
4
5
6
7
8
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "API key sent in the X-API-Key header."
}
}
At the Create step, Auth configuration is preset to API Key and setup asks for the Base URL, the API Key, and an optional Email. Quick sends the value you enter as-is in the header you named, adding or stripping nothing. If the API expects Authorization: Bearer <token>, you enter the whole string Bearer <token> into the API Key field, prefix included, rather than the token on its own. Changing the name in the scheme changes which header carries the value without changing anything you see during setup.

http/bearer

type: http with scheme: bearer is the standard OpenAPI way to describe a bearer token, but the custom OpenAPI import does not map it to a credential field.
1
2
3
"securitySchemes": {
"BearerAuth": { "type": "http", "scheme": "bearer" }
}
When uploaded, the spec validates with no errors and imports cleanly, but at the Create step Auth configuration is set to None with no other choice, and no credential field appears. Because a published API often ships exactly this scheme, you can import a spec expecting bearer auth and end up with a connector that has no way to send the token. To authenticate a bearer token through the import, declare it as an apiKey scheme with "in": "header" and "name": "Authorization", then enter the credential as Bearer <token> in the API Key field.

No authentication

A public API needs no credentials, but the spec still needs a components.securitySchemes block, even an empty one. Omit the components block entirely and the import fails with an error that it cannot read the security schemes. Add an empty block and the import succeeds with Auth configuration set to None:
1
"components": { "securitySchemes": {} }

Conclusion

In this post, you learned about the OpenAPI Specification action connector in Amazon Quick. This connector, allows you to quickly build integrations with your APIs and services not supported by Amazon Quick.
For the full requirements and setup details, see the OpenAPI Specification integration  documentation and the Amazon Quick authentication methods  reference.
Have a question or want to share how you are using Quick? Join the conversation in the Amazon Quick community .
# amazon-quick-suite# amazon-quicksight# agentic-ai
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article