Private, cross-account GraphQL APIs with AppSync Merged APIs

9 minute read
Content level: Intermediate

A walkthrough guide on recent AppSync released features: Private and Merged APIs.

In the realm of distributed systems and secure data sharing, GraphQL has become a valuable option for engineers.

AppSync, an AWS GraphQL offering, has recently released two very promising features: Private and Merged APIs:

This article provides a step-by-step guide to combining the two releases and exposing two private AppSync APIs through a public AppSync Merged API, providing the benefits of both releases.


The architecture involves four accounts:

  • AccountManagement: the account responsible for managing the AWS Organizational Units (OUs) via AWS Organizations.

  • AccountA: hosting a private GraphQL API handling generic products.

  • AccountB: hosting a private GraphQL API handing orders.

  • AccountMerge: hosting the public merged GraphQL API.

The private GraphQL APIs will be shared with the public-facing API via Resource Access Manager (RAM). Architecture

0. Prerequisites

0.1 Setup Organizations

Before you can start creating the APIs, we must structure our cross-accounts setup.

  • Create/reuse an AWS account responsible for managing AWS Organizations, called AccountManagement.

  • In the same account, go to AWS Organizations and create an Organization.

  • Start adding or inviting AWS accounts.

Invite accounts

  • Create/invite AccountA, AccountB and AccountMerge similarly.

Create an account

  • Optionally, you can place the accounts under Organizational Units (OUs) for better management.

  • The Organizational structure should look as this:

Organization structure

For tutorials/troubleshooting on AWS Organizations (out of the scope of this article), please refer to the following: Tutorial: Creating and configuring an organization Access a member account created with AWS Organizations

0.2 Share resources

One last step is to enable sharing on this account. This step is required as I will be sharing private AppSync APIs via Resource Access Manager (RAM), a service that simplifies the process of sharing resources among AWS accounts. To enable resource sharing within your Organization:

  • Open the Settings page in the AWS RAM console.

  • Choose Enable sharing with AWS Organizations, and then choose Save settings.

Sharing your AWS resources

Let’s now follow the steps to create two private APIs and share them with the public Merge API.

1. Create a Product, Private AppSync API

Let’s now create a simple Product API. This will be a private AppSync endpoint, as it can only be accessed by VPC.

  • Go to AccountA.

  • Go to AppSync and Create an API.

  • Create a Product API in AppSync. This starts with the Create API Wizard, which has four steps.

1.1 Select API Type

Select GraphQL APIs and Design from scratch.

Select API Type

1.2 Specify API metadata

Add the API name and select “Use private API features” and then Next”.

API metadata

1.3 Specify GrapQL resources

Create a GrapthQL type backed by a DynamoDB. The table is based on a Product model which four fields (id, title, description and createdAt) and a primary key. Click “Next”.

Specify GraphQL resources

1.4 Review and create

Finally, review the wizard data and click "Create API”.

That’s it. A new private GraphQL API is not created. The next step is to share it with the public Merge API account.

2. Share the Product API

To share the API, we will use the RAM service. It is a cool and underestimated service that allows you to share AWS resources across multiple accounts in a controlled and secure manner. Essentially we will create a shared resource, which refers to an AWS service or component (e.g. an AppSync API…) that can be accessed and utilized by multiple AWS accounts or users within an organization. Let’s see how.

  • Take note of the AWS Account id for the AccountMerge one.

  • In the same account (AccountA), go to RAM.

  • Click on “Create resource share”, which will start a wizard.

RAM shared by me

The wizard consists of 4 steps:

2.1 Specify resource share details

This step requires you to provide a name for the resource share and the resource itself. You can find the resource by filtering the search and searching for “AppSync GraphQL APIs”. Since RAM is a regional service, ensure you are in the same region as you created the AppSync API. If so, the API will appear in the resources list. Select it and click “Next”. The below pictures summarize the sub-steps:

RAM resources details

2.2 Associate managed permissions

This important step specifies which actions principals can perform on shared resources.

  • Click the “Create a customer-managed permissions” button.

  • This opens a new tab where you can define which actions the principals can perform on a resource type in a resource share. Provide a name (e.g. AWSRAMAssociatedMergedAPIAccess) and select “All actions”. This is needed as the accounts’ Merge API must have the appsync:AssociateMergedGraphqlApi access level to correctly associate the private API with the Merge one.

  • Finally, click the “Create a customer managed permissions” button in the new tab. The below picture summarizes the described flow:

Customer-managed permissions

  • Now, back to the Create share resource tab, select the newly created customer managed permission and click “Next”.

RAM - Associate permissions

2.3 Grant access to principals

This step defines the principals that are allowed access to the shared resources. Principals can be part of the same Organization (recommended) or not.

  • Click “Allow sharing only within your organization”.

  • Grab the AccountMerge account id and paste it into the input field.

  • Click “Add”.

  • Select the Principal below

  • Click “Next”.

The below picture gives an overview of the flow:

Grant principles

2.4 Review and create

The last step is to review and finalize the Create resource share wizard; do so and click the Create resource share button.

3. Create an Order, Private AppSync API

The second private AppSync API to be created is about orders. You should repeat the same steps as section 2 but apply for an Orders API.

  • Go to AccountB.

  • Go to Appsync and Create an API.

  • Follow the steps in Section 1, but. This time, you should create an Order model. An example would be three fields (id, quantity, productId), with a partition key for the order id (id field) and a global secondary index to query products.

Specify GraphQL model

  • Finalize the wizard and provision the API.

By the end of this step, you must have an Orders API similar to the below:

Model summary

4. Share the Order API

Now you must repeat the same steps in section 2, but instead, you need to share the orders API with the AccountMerge. This is the account hosting the Merge API, which we will create in the next section.

The shared resource should look like this:

Shared by me RAM

Now comes the time to glue the two APIs into a single, unified Merge API.

5. Create the Merged API

Finally, it is time to put all pieces together. The goal is to create a public-facing AppSync API to merge both the Products and Orders private APIs. To do so:

  • Go to the AccountMerge account.

  • Go to AppSync.

  • Create an API and start the wizard.

5.1 Select API Type

This time, we must select “Merged APIs” and click “Next”.

Select Merged API

5.2 Specify API metadata

  • Provide a name (e.g. MergedProductsAndOrdersAPI)

  • Choose “Create and use a new service role”, as the new merged API requires an IAM role for AWS AppSync to access the imported source API resources at runtime securely.

  • Click “Next”.

Merged API metadata

5.3 Select Sources API

This step allows you to associate the private API created in sections 1 (Products) and 3 (Orders).

  • As they are located in different AWS accounts, click the “Add Source API” button with the “APIs from other AWS accounts” area.

Select Source APIs

  • As we shared both private APIs in sections 2 and 4, they are now visible in this modal. Select them and click “Add Source APIs”

Associate Source APIs

  • Now that Source APIs have been chosen, click “Next”.

Associate Source APIS from another account

5.4 Select authorization mode

This step requires you to select the authorization mode to protect the Merged API with.

  • For simplicity, we choose “API key”.

  • Click “Next”.

Select auth mode

More authorizations mode can be seen here: Merged APIs

5.5 Review and create

Finally, review the wizard data and click “Create API”. Now it is time to test the API.

6. Testing the API

To test the API, we can use the Query editor. Already from there, you can appreciate the result of this merged API:

Query result

Mutations, queries and subscriptions of both APIs have been merged!

Nevertheless, if you now try, for instance, to create a new product, you will encounter this issue:

Not authorized to perform: appsync:SourceGraphQL on resource arn:aws:appsync:<region>:<account_id>:apis/<api_id>

To fix this, we must modify the Merged API execution IAM role created during its wizard.

  • Go to your Merged API.

  • On the left side, click Settings.

  • On the API menu, you will find the execution role link; click it.

AppSync Role to modify

  • You will land in the IAM role. Here, you have complete freedom in the way you want to allow the permission. This is one example:
        "Effect": "Allow",
        "Action": [
        "Resource": [
  • Save the role.

  • Go back now to the query editor, and this time both creation of products, orders and listing works.

Successful query

Another successful query

7. Conclusion

I hope you reached the end of this guide! Congrats.

This article provided a comprehensive guide on creating private GraphQL APIs using AWS AppSync and then merging them into a single public API. By leveraging the features of private APIs and the AppSync Merge API, organizations can address challenges related to API security and cross-team collaboration. This approach enables the consolidation of multiple private APIs into a unified endpoint, offering the benefits of both private access and centralized management.

profile picture
published 8 months ago1421 views

Helpful, Thanks for posting!

profile picture
replied 8 months ago

This article explores the features of Private and Merged APIs in AWS AppSync, a GraphQL offering. Private APIs restrict access to GraphQL APIs within a private network, while Merged APIs consolidate resources from multiple AppSync APIs into a unified endpoint. The article provides a step-by-step guide on combining these features to expose private APIs through a public merged API. The architecture involves four accounts: AccountManagement, AccountA, AccountB, and AccountMerge. Private APIs are shared with the public API via Resource Access Manager (RAM). The article covers prerequisites, creating private APIs, sharing them using RAM, creating a merged API, and testing the API. This approach enables organizations to address API security and collaboration challenges, consolidating multiple private APIs into a single, manageable endpoint.

TL;DR: The article explains how to effectively merge private APIs into a unified endpoint, addressing API security and collaboration challenges.

Thank you for sharing this article. It was informative and insightful.

profile picture
replied 8 months ago