AWS AppSync Auth Link

raw JSON →
4.0.2 verified Thu Apr 23 auth: no javascript

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.

error Unhandled Rejection (Error): No 'region' provided in Auth configuration.
cause The `region` property is missing or null in the configuration object passed to `createAuthLink` for AWS_IAM or Cognito User Pool authentication.
fix
Ensure the config object passed to createAuthLink includes a valid 'region' string, e.g., { url: '...', region: 'us-east-1', auth: {...} }.
error Network error: Unauthorized (HTTP Status 401 or 403)
cause The provided authentication credentials (API Key, JWT, IAM role) are invalid, expired, or the principal lacks permissions to access the AppSync API.
fix
Verify the validity and expiry of your authentication credentials (e.g., API Key, JWT token). For IAM roles, ensure the attached policy grants necessary access to the AppSync API. Double-check your AppSync API's authentication settings in the AWS console.
error TypeError: Cannot read properties of undefined (reading 'concat')
cause One of the Apollo Link instances (e.g., `authLink`, `subscriptionLink`, `httpLink`) in the chain is `undefined` or `null`, often due to a configuration error or failed import.
fix
Ensure all links (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'
cause `@apollo/client` (a peer dependency of `aws-appsync-auth-link`) is not installed in your project.
fix
Install the required peer dependency: npm install @apollo/client graphql rxjs
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`.
fix Migrate your Apollo Client setup to v3.x or v4.x, ensuring `InMemoryCache` and `HttpLink` are correctly imported from `@apollo/client` and links are chained appropriately. Refer to Apollo Client migration guides.
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.
fix Ensure your `config` object passed to `createAuthLink` includes `url`, `region`, and a correctly structured `auth` object matching your AppSync API's authentication type, including necessary credentials (e.g., `apiKey`, `jwtToken`, `credentials`).
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.
fix Install `aws-appsync-subscription-link` (`npm install aws-appsync-subscription-link`) and integrate `createSubscriptionHandshakeLink` into your Apollo Link chain, usually before the `httpLink`.
npm install aws-appsync-auth-link
yarn add aws-appsync-auth-link
pnpm add aws-appsync-auth-link

This quickstart demonstrates how to initialize Apollo Client with `aws-appsync-auth-link` and `aws-appsync-subscription-link` for an AppSync API using API Key authentication. It correctly chains the necessary Apollo Links and configures the client.

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));