Registry / aws / aws-appsync-auth-link

aws-appsync-auth-link

JSON →
library4.0.2jsnpmunverified

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.

npm install aws-appsync-auth-link
INSTALL
IMPORT
SIG · AWS-APPSYNC-AUTH-L
A
aws-appsync-auth-link
awsjavascriptv4.0.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createAuthLink
import { createAuthLink } from 'aws-appsync-auth-link';
const createAuthLink = require('aws-appsync-auth-link').createAuthLink;
Prefer ESM imports for modern applications. CommonJS 'require' style is generally discouraged for new projects.
AUTH_TYPE
import { AUTH_TYPE } from 'aws-appsync-auth-link';
const AUTH_TYPE = require('aws-appsync-auth-link').AUTH_TYPE;
An enum providing constants for supported AppSync authentication types (e.g., API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS).
AuthLinkHTTPOptions
import type { AuthLinkHTTPOptions } from 'aws-appsync-auth-link';
Type import for configuring the authentication link. Useful for TypeScript projects to ensure correct configuration structure.

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));
Debug
Known issues
breakingMajor 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.
affects: >=4.0.0
gotchaImproperly 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`).
affects: >=1.0.0
gotchaFor 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`.
affects: >=1.0.0
Errors
Common errors & fixes
Unhandled Rejection (Error): No 'region' provided in Auth configuration.
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: {...} }`.
Network error: Unauthorized (HTTP Status 401 or 403)
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.
TypeError: Cannot read properties of undefined (reading 'concat')
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.
Module not found: Error: Can't resolve '@apollo/client'
`@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`
Upgrade
Version history
4.0.2latest on npm
Audit
Dependencies
@apollo/clientrequiredRequired for creating Apollo Client instances and linking capabilities.
graphqlrequiredCore dependency for GraphQL operations.
rxjsrequiredUsed internally for handling asynchronous operations and observables.
Agent activity
44 hits · last 30 days
node
36
OpenAI (training)
2
Resources
aws-appsync-auth-link — npm install aws-appsync-auth-link · libregistry