# API Gateway portals You can use an API Gateway portal to share your APIs and API documentation with API consumers in a web page. A portal contains a set of *portal products*. Each portal product is a logical grouping of REST APIs and contains the documentation that you create and publish for your API consumers. Product pages within a portal contain the custom documentation at the portal product level. *Product REST endpoint pages* contain the documentation for each of the REST APIs and the path, method, and stage of a REST API. The combination of product pages and product REST endpoint pages provide the complete documentation to allow API consumers to learn how to start using your REST APIs. Use a portal to do the following: + Use API Gateway for your entire API lifecycle, from creating your APIs to documenting and distributing them. + Share portal products across AWS accounts. + Customize and share a central location for your portal products and provide product pages. ## Considerations The following considerations might impact your use of API Gateway portals: + You can only create portals to share REST APIs. + Portals are created at the AWS Region level. Your portal can only contain REST APIs that are in the same Region where you create the portal. + You can only use the AWS Management Console, AWS CLI, or AWS SDKs to create and share your portals. + You can only control access to your portal using Amazon Cognito user pools. Your portal consumers can either sign in directly through a user pool, or they can federate through a third-party identity provider (IdP). If you use an Amazon Cognito user pool, you cannot set a client secret for your user pool. For more information, see [Amazon Cognito user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html). # Portal products in API Gateway A *portal product* represents a service or functionality that you want to share. Your portal product is a collection of product REST endpoints and product pages. *Product REST endpoints* are the access points to your portal product, and they consist of the path and method of a REST API and the stage it's deployed to. *Product pages* are documentation that you provide to explain how API consumers can use your product endpoints. A portal product can contain the entire `Prod` stage as a collection of product REST endpoints or just the `GET /pets` resource deployed to the `Prod` stage as a singular product REST endpoint. Your portal product is customizable. You can add custom documentation, rename the product REST endpoints, reorganize the display order, add new sections, and share products across AWS accounts. In order for any changes you make to your portal product to take effect, you must republish any portals that use your portal product. ## Pet adoption portal product example As an example, you could have multiple REST APIs that represent a pet adoption service. You could use API Gateway to create a `pet adoption` portal product. This portal product would help customers discover which APIs they should use to meet and adopt pets. This portal product uses REST APIs that you already created, but it allows you to regroup and organize them. You can also provide documentation about the terms and conditions of using your pet adoption portal product and let customers try out your APIs. This information is all stored in your portal product. The following table shows three APIs that represent a pet adoption portal product, and their corresponding product REST endpoint operation names and page section names. | REST API ID | REST API path and method | REST API stage | Operation name | Page section | | --- | --- | --- | --- | --- | | kf5387miad | GET /dogs | Prod | View dogs | AdoptAnimals | | kf5387miad | GET /dogs/\$1dogId\$1 | Prod | View dog | AdoptAnimals | | ra8obxcevg | GET /cats | Prod | View cats | AdoptAnimals | | ra8obxcevg | GET /cats/\$1catId\$1 | Prod | View cat | AdoptAnimals | | h0rpx9cm62 | ANY /user/\$1userId\$1/\$1petId\$1\$1 | Beta | Request visit | AdoptProcess | In this example, two REST APIs, `ra8obxcevg` and `kf5387miad`, are grouped together in the `AdoptAnimals` section. The result of this ordering navigation would look like the following in a portal: ![\[Pet adoption portal\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/apigateway-portal.png) Because the `ANY` method is a catch-all method, the portal shows all the supported HTTP methods. This portal also contains documentation that was created by the portal product owner. ## Next steps To get started with portal products, you can do the following: + To create a portal product, see [Create a portal product in API Gateway](apigateway-portals-create-portal-product.md). + To learn about the try it functionality, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). + To learn about product pages, see [Create a product page in API Gateway](apigateway-portals-create-product-page.md). + To learn about sharing your portal product, see [Share portal products in API Gateway](apigateway-portals-share-resources.md). After you create a portal product, you can publish it to a portal. For more information, see [Create a portal in API Gateway](apigateway-portals-create-portal.md). # Create a portal product in API Gateway The following procedure shows how to create a portal product. A portal is a collection of *portal products*. After you create your portal product, you create product REST endpoints and product pages. To learn about portal products, see [Portal products in API Gateway](apigateway-portals-portal-product.md). ## Considerations The following considerations might impact how you create a portal product: + Your portal product can contain both private and public REST APIs. Private APIs aren't supported for the try it functionality and, as a result, have a visual difference in your portal. As a portal owner, you might need to provide documentation to explain this. + If you create your portal product using the AWS CLI or AWS SDKs, your portal won't have any product endpoints or product pages. You need to add these resources using the AWS CLI or console. To learn how to create a product REST endpoint, see [Create a product REST endpoint in API Gateway](apigateway-portals-create-product-rest-endpoint.md). To learn how to create a product page, see [Create a product page in API Gateway](apigateway-portals-create-product-page.md). ## Create a portal product The following procedure shows how to create a portal product. **To create a portal product** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose **Create product**. 1. For **Product name**, enter the name of your portal product. 1. For **Product description**, enter a description. 1. Choose **Next**. 1. To select your product REST endpoints, under **API endpoints** choose an API, and then choose a stage. 1. To add an endpoint to your product REST endpoints, select the API endpoint, and then choose **Add to product**. **Note** Do not choose **Next** without first choosing **Add to product**. ![\[Portal product\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/apigateway-portal-product.png) The API endpoint will appear in the **Selected API endpoints** list. 1. Choose **Next**. 1. Review your selection and choose **Create product**. After you create your portal product using the console, all your product pages and product REST endpoint pages are drafts and won't appear in a portal. To have your product pages and product REST endpoint pages visible to consumers, you need to add your draft to a section. If you create your portal product using the AWS CLI or AWS SDKs, you add the draft to the section in the AWS CLI command. Regardless of how you add your draft to a section, you must publish the portal that uses your portal products for it to be visible to consumers. **To add your draft to a page section** 1. Your drafts are listed in the **Documentation** tab. There are **Draft documentation pages** for your product pages and **Draft API reference pages** for your product REST endpoint pages. Choose **Draft API reference pages**. 1. Choose a draft API reference page. If you don't have any product REST endpoints, you won't have any draft API reference pages. To learn how to create a product REST endpoint, see [Create a product REST endpoint in API Gateway](apigateway-portals-create-product-rest-endpoint.md). 1. Choose **Edit page**. 1. On this page, you can overwrite any existing API documentation parts or use the API Gateway documentation. To allow the contents of your product REST endpoint page to be visible to consumers, under **Section name**, enter a name. If this was the `/pets-GET` endpoint, the page name could be `Pets`. 1. Choose **Save changes**. 1. The new page name you created appears under the **API reference pages** section. To allow the new page to be visible to consumers, you still need to republish your portal. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Create a product REST endpoint in API Gateway A product REST endpoint is an access point to your portal product. Each endpoint consists of the path and method of a REST API and the stage it's deployed to. The endpoint includes any documentation you've defined for your REST API, or can be updated with custom documentation. When you create your product REST endpoint, you configure the following settings: + The product REST endpoint's operation name. If your REST API has the path and method `GET /pets`, in a portal, the name is `/pets`. Using the operation name, you can change the product REST endpoint name to `Pet summaries`. This doesn't impact your existing API. + The try it functionality for your product endpoint. This lets API consumers try your APIs in your portal. If you create a product endpoint for a private API, the try it functionality is set to `UNAVAILABLE`. For more information, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). + If you currently have documentation parts defined for your REST API, you can either import the documentation or override your existing documentation and create new product-level documentation using [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). Any documentation overrides do not propagate back to your API Gateway API documentation parts. If you import your current documentation parts, API Gateway syncs changes across your API to your product REST endpoint. ## Create a product REST endpoint The following procedure shows how to add a product REST endpoint to an existing portal product. To learn how to create a portal product and a product REST endpoint together, see [Create a portal product in API Gateway](apigateway-portals-create-portal-product.md). **To create a product REST endpoint for a product portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a portal product. 1. Choose the **Associated endpoints** tab, and then choose **Add endpoints**. 1. To select your product REST endpoints, under **API endpoints** choose an API, and then choose a stage. 1. To add an endpoint to your product REST endpoints, select the API endpoint, and then choose **Add to product**. The API endpoint will appear in the **Selected API endpoints** list. 1. Choose **Submit**. 1. Your product REST endpoint page is now a draft. Choose **Draft API reference pages**, and then choose your product REST endpoint page to finalize the content of the page. 1. Choose **Edit page**. 1. To override the existing API Gateway documentation, for **Documentation source**, turn on **Override the documentation** and do the following: 1. For **Display content**, choose **Create override**. 1. For **Operation name**, enter a new operation name. 1. For **Page body**, enter your custom documentation. 1. (Optional) For **Endpoint**, enter a custom endpoint that appears in your portal. 1. To let customers invoke your API in your portal, select **Try it functionality**. For more information, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). 1. For **Section name**, enter a name or choose an existing section. When you add your product REST endpoint to a section, consumers can view your content on a published portal. 1. Choose **Save changes**. To allow the new page to be visible to consumers, you still need to republish your portal. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Create a product page in API Gateway A product page helps your product consumers understand and use your products. The documentation is at the product-level, so any portals that include your product have this documentation. API Gateway supports two types of product pages written in [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax): Overview page When you create your product, API Gateway automatically generates an **Overview** page for your product based on the information you provide when you create your product. This page has additional formatting that can't be changed. You can modify the text or remove the page from the portal product. Custom pages A custom page is a page written in Markdown. You might use this section for terms and conditions or a tutorial on how to use your product. You can change any custom page into an overview page. When you change a custom page into an overview page, the page content is formatted to match the overview page. ## Considerations The following considerations might impact your use of product pages: + This documentation is not at the API-level and doesn't include any methods, resources, or any request parameters. To learn how to modify the documentation at the API-level for a product, see [Update a product REST endpoint in API Gateway](apigateway-portals-update-product-endpoint.md). + You can't directly upload a `.md` file to your product. + You can modify the order of the product pages by modifying the page list in the display order of your portal product. For more information, see [Update a portal product in API Gateway](apigateway-portals-update-portal-product.md). + You need to republish any portals that include your product for documentation changes to take effect. + If you have multiple portals that use the same portal product, the product pages are the same across all portals. To have the same product REST endpoints but different product pages, create multiple products. ## Create a product page The following procedure shows how to create a product page. **To create a product page** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. Under **Documentation**, choose **Create custom page**. 1. For **Page title**, enter the page title. 1. For **Body**, enter your supplemental documentation using GitHub Flavored Markdown. The **Preview** section shows how your content appears in a portal. The final visual style might change based on your portal settings. 1. Choose **Create product page**. 1. Your product page is now a draft. Choose **Draft documentation pages**, and then choose your product page to finalize the content of the page. 1. Choose **Edit page**. 1. For **Section name**, enter a name or choose an existing section. When you add your product page to a section, consumers can view your content on a published portal. 1. Choose **Save changes**. To allow the new page to be visible to consumers, you still need to republish your portal. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Update a portal product in API Gateway When you update a portal product, you can change the name, description, or the display order of how your product REST endpoints and product pages appear. To modify the display order, you modify the page list for product pages and the section name for product endpoints. If you do this using the AWS CLI or SDKs, you specify the product page ARN or the product REST endpoint ARN. You need to republish any portals that use your products for your API consumers to see the changes reflected in a portal. ## Update a portal product The following procedure shows how to change the section list to reorder the product REST endpoints as they will appear in a portal. In this procedure, we assume you have at least two product REST endpoints in your portal product. **To update a portal product** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Documentation** tab, for **Product pages**, choose **Manage**. 1. Drag and drop the product REST endpoints to reorder them. You can also move product REST endpoints and product pages into the draft pages section. Pages in the draft pages are won't be visible in your portal. 1. (Optional) Rename the product REST endpoint names or add a new API reference section. These changes won't impact your REST APIs. 1. Choose **Save changes**. # Update a product REST endpoint in API Gateway When you update a product REST endpoint, you can change all the settings of the product endpoint except for the path and method of a REST API and the stage it's deployed to. Any changes to your product endpoints are updated automatically, but you need to republish any portals that use your products to see the changes reflected in a portal. ## Update a product REST endpoint The following procedure shows how to update a product REST endpoint to overwrite the current API documentation with custom API reference documentation. **To update a product REST endpoint** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Documentation** tab, under **API reference pages**, choose the name of a product REST endpoint, such as **/dogs - GET**. 1. For **Preview**, choose **Edit page**. 1. For **Documentation source**, turn on **Override the documentation**. 1. For **Display content**, choose **Override the existing content**. If you choose **Remove all content**, the content is removed from the page, but you can choose **Override the existing content** to access the documentation again. 1. In **Page body**, enter custom API reference documentation using [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). This documentation will not propagate back to API Gateway. 1. Choose **Save changes**. 1. You must republish any portals that use this portal product for the changes to take effect. # Update a product page in API Gateway When you update a product page, you can change all the settings of the product page. Any changes to your product page are updated automatically, but you need to republish any portals that use your products to see the changes reflected in a portal. # Share portal products in API Gateway You can share a portal product across AWS accounts using AWS RAM. When you share a portal product, the other account can use your portal product in their own portal. With shared portal products, you can create a single catalog of your organization's APIs and enforce governance standards across your API ecosystem. At the same time, sharing portal products provides flexibility for API providers to develop, test, and maintain APIs in their own accounts. ## Considerations The following considerations might impact how you share portal resources: + When you share your product with another account, that account cannot modify any properties of your REST API. This includes the integration endpoints, the authorization strategy, or the stage configuration. + When you add another account's portal product into your portal, the portal product owner cannot view or control any other properties of your portal. The portal product owner only knows that the product is being used in your portal. + API Gateway portal products are shared at the AWS Region level. + You can use one resource share with multiple principals, and after you create the resource share, you can add more principals to it. We recommend that when possible, you reuse your resource share. + If both accounts are in the same organization using AWS Organizations, the resource share is automatically accepted. You still need to create the resource share using AWS RAM. + If both accounts are in the same organization using AWS Organizations and resource sharing within your organization is enabled, any principals in the organization that you share with are automatically granted access to the resource shares. There is no need for an invitation and you can skip the resource share. + If the account you shared the product with doesn't accept the resource share within **12 hours**, you must share the resource again. + After you create the resource share, AWS RAM updates the product sharing policy of your product to prevent access to principals without explicit `allow` access. For more information, see [Determining whether a request is allowed or denied within an account](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow) in the IAM User Guide. The updated resource policy will look like the following: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:GetProduct", "apigateway:ListEndpoints", "apigateway:ListPages", "apigateway:GetEndpoint", "apigateway:GetPage" ], "Resource": [ "arn:aws:apigateway:us-east-1:111122223333:/portalproducts/product-id", "arn:aws:apigateway:us-east-1:111122223333:/portalproducts/product-id/*" ] } ] } ``` AWS RAM has prevented principals without explicit allow access to add your product to their portal, by adding the following: ``` "StringNotEquals": { "aws:PrincipalAccount": "555555555555" } ``` To learn how to share a product, see [Share your portal product with a portal owner in API Gateway](apigateway-portals-share-products.md). To learn how to add a product shared with you to your portal, see [Add a shared portal product to your portal in API Gateway](apigateway-portals-use-shared-products.md). # Share your portal product with a portal owner in API Gateway As a product owner, you can share your product with a portal owner in another AWS account using AWS RAM. You maintain full control of all product pages and product REST endpoint pages. ## Considerations The following considerations might impact how you share portal products: + You can share or unshare your portal products at any time. If you unshare a portal product while it's being used in a published portal, the portal owner won't be able to view the portal product, view any updates made to it, or republish or preview the portal until they remove the portal product. + You can view the portal products that you've shared with other accounts. + You can't modify any portals that contain your portal product, unless you create the portal yourself. ## Share your portal product The following procedure shows how to create a resource share. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Creating a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-create.html) in the *AWS RAM User Guide*. For **Select resource type**, choose **API Gateway Product**. ------ #### [ AWS CLI ] The following [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) creates a resource share for your private custom domain name. It can take a few minutes for the resource and principal associations to complete. For principals, provide an account ID or an Organizations ID, such as `arn:aws:organizations::123456789012:organization/o-1234abcd`. You can provide multiple principals for your resource share. ``` aws ram create-resource-share \ --region us-west-2 \ --name portal-product-resource-share \ --permission-arns arn:aws:ram::aws:permission/AWSRAMDefaultPermissionAPIGatewayDeveloperPortalProduct \ --resource-arns arn:aws:apigateway:us-west-2:111122223333:/portalproducts/p000000000 \ --principals 222222222222 ``` ------ To unshare your portal product, use AWS RAM to delete the resource share. At any time, you can modify the product sharing policy to modify which principals can use your portal products in their portals. **To update the product sharing policy** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Product sharing** tab, for **Product sharing policy**, choose **Manage product sharing policy**. 1. If you haven't shared your product before, your product sharing policy will deny all access to other accounts to your portal products. You need to update the policy to allow access for certain accounts to your portal product. 1. After you have updated your product sharing policy, choose **Save changes**. # Add a shared portal product to your portal in API Gateway As a portal owner, you can use portal products shared with you by other accounts in your portal. You maintain full control of your portal. ## Considerations The following considerations might impact how you share portal resources: + You must accept the product resource share from the product owner to use their product in your portal. If you and the product owner are in the same Organizations, AWS RAM can complete some sharing steps for you. + If the product owner unshares a product while it's in your published portal, the product will still be visible on the portal, but you won't be able to publish the portal again until you remove this product. It's your responsibility as the portal owner to remove the product from your portal, as the product owner can't do that for you. + You can view the portal products, the product pages, and the product REST endpoint pages, but you cannot modify any of these resources. + If a product is shared with you, you can't share it with another account. ## (Optional) Accept the resource share After your product owner creates a resource share, you have **12 hours** to accept it. If you are in the same organization using AWS Organizations as the product owner, the share is automatically accepted. If you are in an organization that has automatic shared resources enabled, the resource is automatically shared with you. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Accepting and rejecting resource share invitations](https://docs.aws.amazon.com/ram/latest/userguide/working-with-shared-invitations.html) in the *AWS RAM User Guide*. ------ #### [ AWS CLI ] To find all the resources shared with you, use the following [get-resource-share-invitations](https://docs.aws.amazon.com/cli/latest/reference/ram/get-resource-share-invitations.html) command: ``` aws ram get-resource-share-invitations \ --region us-west-2 ``` Use the resulting resource share ARN to accept the resource share invitation. The following [accept-resource-share-invitation](https://docs.aws.amazon.com/cli/latest/reference/ram/accept-resource-share-invitation.html) command accepts the resource share. ``` aws ram accept-resource-share-invitation \ --resource-share-invitation-arn arn:aws:ram:us-west-2:123456789012:resource-share-invitation/1e3477be-4a95-46b4-bbe0-c4001EXAMPLE \ --region us-west-2 ``` ------ ## Add a shared product to your portal After you accept the resource share, you add the product to your portal. ------ #### [ AWS Management Console ] **To add a shared product to your portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. In the **Products** tab, for **Portal products**, choose **Add products**. 1. Add a product to your portal. Shared products are shown as `shared` in the products list. 1. Choose **Save changes**. ------ #### [ AWS CLI ] To find all the portal products shared with you, use the following `get-portal-products` command: ``` aws apigatewayv2 get-portal-products \ --resource-owner OTHER_ACCOUNTS \ --region us-west-2 ``` To add a shared portal product to your portal, use the following `update-portal` command: ``` aws apigateway update-portal \ --included-portal-product-arns arn:aws:apigateway:us-west-2:111122223333:/portalproducts/p000000000 \ --region us-west-2 ``` ------ # Enable try it for an API Gateway product REST endpoint in your portal Use try it to let an API consumer invoke your product endpoint from your portal. When an API consumer uses try it, they enter method request parameters and invoke your product endpoint. Then, API Gateway invokes your API over the public internet and returns the response in the try it window. You can use a custom product page to provide any additional information about required parameters to access your API. API Gateway uses the following limits to protect your APIs: + API Gateway only allows 3 requests per second to your API. + API Gateway uses a built-in timeout limit of 29000 ms. Your actual API might have a higher timeout limit, but API Gateway does not apply this timeout when a customer uses try it. + API Gateway limits the response payload to 6MB. ## Considerations The following considerations might impact how you use try it: + Try it is not supported when you preview a portal. + Try it is not supported for the REST APIs with the following features: + Private APIs + APIs that use mutual TLS + APIs that use private or self signed SSL certificates As the portal owner you are responsible for communicating with your API consumers the reasoning of the why try it button isn't there for any REST APIs that aren't supported. API Gateway does not explain this for you. ## Enable try it for a product REST endpoint The following procedure shows how to enable try it for a product endpoint. To learn how to use try it in a portal, see [Use an API Gateway portal](apigateway-portals-use-portal.md). **Enable try it for a product REST endpoint** 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Documentation** tab, under **API reference pages**, choose the name of a product REST endpoint, such as **/dogs - GET**. 1. Choose **Edit page**. 1. To let customers invoke your API in your portal, select **Try it functionality**. 1. Choose **Save changes**. 1. You must republish any portals that use this portal product for the changes to take effect. # Delete a portal product in API Gateway When you delete a portal product, it cannot be recovered. ## Delete a portal product The following procedure shows how to delete a portal product. **To delete a portal product** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a portal product. 1. Choose **Delete**. 1. Confirm your choice and choose **Delete**. 1. You must republish any portals that use this portal product for the changes to take effect. # Create a portal in API Gateway A portal is a collection of products. You control the authorization, branding, and publication of your portal. When you create a portal, its publish status is `Disabled`. This means your portal is not discoverable on the web. To let consumers access your portal, you need to publish it. Before you publish your portal, you can also preview it. API Gateway supports portals on the following browsers: + Firefox + Google Chrome + Microsoft Edge + Safari ## Choose a domain name By default, your portal URL is hosted at the following Amazon-owned domain name: ``` https://p-portalId.apigw-portal.us-east-1.on.aws ``` To customize the domain name, you can provide a domain name that you own and an SSL certificate for the custom domain. The certificate must be managed with [AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/) (ACM) in US East (N. Virginia) and be supported by Amazon CloudFront. For more information, see [Requirements for using SSL/TLS certificates with CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-and-https-requirements.html). When you use a custom domain name, API Gateway creates a CloudFront distribution, secured in transit with your ACM certificate. Then, API Gateway provides an alias record, which you add to your DNS configuration. The alias record is the Amazon-owned domain name. You must add this alias record to direct traffic to the CloudFront distribution for your custom domain. The domain name you provide must be unique and not already be used by the aliases list on an existing CloudFront distribution. If you use your own domain name, API Gateway uses the `TLS_1_2` security policy to protect your portal. For more information, see [Supported protocols and ciphers between viewers](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/secure-connections-supported-viewer-protocols-ciphers.html). You can't change this value. ## Create a portal You use the API Gateway console to create and configure your portal. The following procedures guide you through all required steps. You can also choose **Skip to Review and create** at the end of the first procedure to create an empty portal. The following procedure shows how to create a portal. First, you define your portal details. **To define your portal details** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose **Create portal**. 1. Under portal details, for **Portal name**, enter a name. 1. For **Portal description**, enter a description. 1. For **Portal authorization**, select how to authorize your portal. + If this is your first time creating a portal, we recommend that you choose **None**. If you plan on adding any production APIs to your portal, use **Require authorization**. + To require portal consumers to authenticate to use your portal, choose **Require authorization**, and do the following: 1. For **Amazon Cognito user pool**, select your user pool. The user pool must be in the same Region as your portal. 1. For **Application client ID**, choose the app client ID. In your app client, you must set the callback URL to the portal's default URL. 1. For **User pool domain**, enter the user pool domain. For more information, see [Configuring a user pool domain](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain.html). 1. For **Domain configuration**, select the domain name for your portal. + If this is your first time creating a portal, we recommend that you choose **Default domain**. Once you publish your portal, it will be available at `https://p-portalId.apigw-portal.us-east-1.on.aws`. + To provide a custom domain name that you own, select **Custom domain name** and do the following: 1. For **Domain name**, enter a fully qualified domain name. 1. For **ACM certificate**, choose an ACM certificate that covers the domain name. You'll need to add the alias record that API Gateway provisions to your DNS record, in order to serve traffic from your portal. 1. To add a CloudWatch RUM app monitor to your portal, for **RUM app monitor**, choose an app monitor. For more information, see [CloudWatch RUM](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM.html). 1. Choose **Next**. After you define your portal details, you add portal products. You can change the portal products in your portal at any time, but you need to republish your portal for the changes to take effect. **To select your portal products** 1. From the resource list, select the products to add to your portal. 1. Choose **Next**. After you select your products, you customize the portal design. To upload a portal logo, you must have an image uploaded to Amazon S3. You can change these values at any time, but you need to republish your portal for the changes to take effect. **(Optional) To customize your portal** 1. For **Portal logo**, provide the S3 URI for your file. Only `.svg`, `.png`, or `.jpg` are supported. 1. To customize the design of your portal, you have two options: 1. You can choose **Portal theme** to apply a pre-made color theme on your portal. 1. You can use the color selectors to select all your portal design options. 1. Choose **Next**. After you select the portal design, review the information for the portal. **To review your portal** + Review your settings on the review and create page. When you're satisfied with the settings, choose **Create**. If you use an Amazon Cognito user pool to control access to your portal, you must set the callback URL to the portal's default URL in the app client. For more information, see [Application-specific settings with app clients](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html). Your portal won't be available to consumers after you create it. You must publish your portal for it to be accessible on the internet. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Update a portal in API Gateway You can update the theme, logo, or the portal products in your portal. When you update your portal, the changes don't take effect until you republish your portal. ## Update a portal The following procedure shows how to update the design of a portal. **To update a portal design** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. In the **Portal design** tab, choose **Edit**. 1. To update the portal logo, choose **Update portal logo**. You can either remove the existing logo or use a new logo. 1. Make any theme or background updates to your portal design. 1. Choose **Save changes**. 1. (Optional) Choose **Generate portal preview** to see your changes. After you've confirmed your changes, publish your portal. 1. Choose **Publish portal**. 1. Enter a description for your portal update and choose **Publish**. # Preview a portal in API Gateway You can preview your portal before you publish it. API Gateway creates a short-lived URL that you can use to preview the version of your portal that customers will see once your portal is published. ## Considerations The following considerations might impact how you preview a portal: + Try it is not enabled for your preview portal. For more information, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). ## Preview a portal The following procedure shows how to preview a portal. **To preview a portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. Choose **Generate portal preview**. Do not refresh your page. 1. After API Gateway generates your preview, choose **Open portal preview**. Your portal preview will open in a new tab. # Publish a portal in API Gateway For API consumers to access your portal, you must publish it. A portal URL can be discovered by anyone on the internet. We recommend that you preview and secure your portal before publishing it. ## Considerations It might take API Gateway a few minutes to publish your portal. You can monitor the **Publish status** in the console. ## Publish a portal The following procedure shows how to publish a portal. **To publish a portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. Choose **Publish portal**. 1. (Optional) For **Description of changes**, enter a description of your change. When you publish a portal, we recommend that you always provide a brief description of your changes. 1. Choose **Publish**. It takes API Gateway a few minutes to finish publishing your portal. API Gateway provides a link to your portal when it's available. To delete your portal, you must disable it first. For more information, see [Disable a portal in API Gateway](apigateway-portals-disable-portal.md). # Use an API Gateway portal After you publish your portal, it's available on the web. To use your portal, copy the **Portal default domain name** or the **domain name** and enter it in a browser. If your portal uses a domain name, the default domain name can't be used to access your portal. ## Use a portal The following procedure shows how to access a portal and use try it for a product REST endpoint. **To use a portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. Copy the **Portal default domain name** or the **domain name** and enter it in a browser. 1. On the portal homepage, you can search for portal products and discover product pages. Use the search at the top of the portal to search all the content in your portal. Use the search bar under **Products** to search for portal products. 1. Choose a portal product. 1. Choose a product REST endpoint. 1. In the **Try it** window, enter parameters to try a call to your API. 1. Choose **Try it**. API Gateway will invoke your API and show the results in the window. ## Troubleshoot your portal The following provides troubleshooting advice for errors and issues that you might encounter when using a portal. ### The portal webpage site can’t be reached If you receive an error message that the portal webpage site can't be reached, make sure you published your portal. If you used a domain name, make sure that you added the alias record that API Gateway provided to direct traffic to the CloudFront distribution for your custom domain. ### Try it failed If you are unable to use try it for a product REST endpoint, make sure that the try it state is `ACTIVE`. In addition, make sure you entered the correct parameters to invoke your API. ### Pages are not appearing in your portal If you created a product REST endpoint page or a product page and it's not visible in your portal, make sure your pages are not drafts. To verify this, do the following: **To verify your pages are not in drafts** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose your portal product. 1. In the **Documentation** tab, confirm your pages are not in the **Draft documentation pages** or **Draft API reference pages** section, but are in the **Custom documentation pages** or **API reference pages**. # Disable a portal in API Gateway When you disable a portal, your portal is no longer available on the web. After you disable a portal, you can either delete the portal or republish it if necessary. ## Disable a portal The following procedure shows how to disable a portal. **To disable a portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. Choose **Actions**, and then choose **Disable portal**. 1. Confirm your choice and choose **Disable portal**. The **Publish status** will change to **Disabled**. To remove the disable status of the portal, publish the portal again. # Delete a portal in API Gateway When you delete a portal, it cannot be recovered and you must disable it first. If you want to remove your portal from the web, you can disable it. This lets you modify your portal and republish it later. ## Delete a portal The following procedure shows how to delete a portal. **To delete a portal** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. If your portal is not disabled, disable it by choosing **Actions**, **Disable portal**. It takes a few minutes for your portal to be disabled. You can monitor the **Publish status** to see when your portal publish status is disabled. 1. After you have unpublished your portal, you can delete it. To delete your portal, choose **Actions**, **Delete portal**. Confirm your choice and choose **Delete**.