AWS AppSync Auth Link
raw JSON →The `aws-appsync-auth-link` package provides a specialized Apollo Link for integrating AWS AppSync authentication with Apollo Client in JavaScript and TypeScript applications. It is part of the `aws-mobile-appsync-sdk-js` repository and is currently at version 4.0.2. This link allows developers to configure various AWS AppSync authentication modes, including API Key, AWS IAM, Amazon Cognito User Pools, and OpenID Connect, by injecting the necessary authentication headers into GraphQL requests. Its primary differentiator is its seamless integration with the Apollo Client ecosystem, abstracting away the complexities of signing requests for AppSync. The package's release cadence tends to align with major Apollo Client versions, with a significant jump from v1 to v4 to maintain compatibility with `@apollo/client` v3.x and v4.x, implying potentially infrequent but impactful updates.
Common errors
error Unhandled Rejection (Error): No 'region' provided in Auth configuration. ↓
createAuthLink includes a valid 'region' string, e.g., { url: '...', region: 'us-east-1', auth: {...} }. error Network error: Unauthorized (HTTP Status 401 or 403) ↓
error TypeError: Cannot read properties of undefined (reading 'concat') ↓
authLink, subscriptionLink, httpLink) are correctly instantiated and not null before chaining them together using .concat(). Check your imports and configuration parameters for any typos or missing values. error Module not found: Error: Can't resolve '@apollo/client' ↓
npm install @apollo/client graphql rxjs Warnings
breaking Major breaking changes occurred when upgrading from `aws-appsync` v1.x (and older `aws-appsync-auth-link` versions) due to the underlying Apollo Client peer dependency shifting from v2.x to `>=3.0.0`. ↓
gotcha Improperly configured `auth` object in the AppSync configuration can lead to authentication failures (e.g., `Unauthorized` errors) or issues like missing `region` in the request signing process. ↓
gotcha For real-time subscriptions with AppSync, `aws-appsync-subscription-link` is typically required alongside `aws-appsync-auth-link` to handle the WebSocket handshake, even if the primary authentication is handled by the auth link. ↓
Install
npm install aws-appsync-auth-link yarn add aws-appsync-auth-link pnpm add aws-appsync-auth-link Imports
- createAuthLink wrong
const createAuthLink = require('aws-appsync-auth-link').createAuthLink;correctimport { createAuthLink } from 'aws-appsync-auth-link'; - AUTH_TYPE wrong
const AUTH_TYPE = require('aws-appsync-auth-link').AUTH_TYPE;correctimport { AUTH_TYPE } from 'aws-appsync-auth-link'; - AuthLinkHTTPOptions
import type { AuthLinkHTTPOptions } from 'aws-appsync-auth-link';
Quickstart
import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';
import { createAuthLink, AUTH_TYPE } from 'aws-appsync-auth-link';
import { createSubscriptionHandshakeLink } from 'aws-appsync-subscription-link';
// Replace with your AppSync endpoint and API key/region
const APPSYNC_URL = 'https://YOUR_APPSYNC_ID.appsync-api.YOUR_REGION.amazonaws.com/graphql';
const APPSYNC_REGION = 'us-east-1'; // e.g., 'us-east-1'
const APPSYNC_API_KEY = process.env.APPSYNC_API_KEY ?? 'da2-YOUR_APPSYNC_API_KEY';
// Configuration object for AppSync
const awsAppSyncConfig = {
url: APPSYNC_URL,
region: APPSYNC_REGION,
auth: {
type: AUTH_TYPE.API_KEY,
apiKey: APPSYNC_API_KEY,
},
};
// 1. Create the authentication link
const authLink = createAuthLink(awsAppSyncConfig);
// 2. Create the HTTP link for queries and mutations
const httpLink = new HttpLink({ uri: awsAppSyncConfig.url });
// 3. Create the subscription handshake link (required for real-time subscriptions)
// Note: aws-appsync-subscription-link is a separate package
const subscriptionLink = createSubscriptionHandshakeLink(awsAppSyncConfig);
// Chain the links in the correct order:
// authLink -> subscriptionLink (for WebSocket handshake) -> httpLink (for HTTP requests)
const link = authLink.concat(subscriptionLink).concat(httpLink);
// Initialize Apollo Client
const client = new ApolloClient({
link: link,
cache: new InMemoryCache(),
});
console.log('Apollo Client initialized with AWS AppSync authentication and subscription links.');
console.log('AppSync Endpoint:', awsAppSyncConfig.url);
console.log('Authentication Type:', awsAppSyncConfig.auth.type);
// Example of a basic query (requires 'graphql-tag' for gql template literal, not included here)
// import { gql } from '@apollo/client';
// client.query({
// query: gql`
// query MyQuery {
// listItems {
// items {
// id
// name
// }
// }
// }
// `
// }).then(response => console.log('Query Data:', response.data))
// .catch(error => console.error('Query Error:', error));