The `onegraph-auth` library provides essential client-side authentication helpers for integrating web applications with a multitude of third-party services via the OneGraph platform. It streamlines the complex OAuth login and logout flows, manages session state, and securely handles token storage in the browser. The package is currently at version 4.0.2, indicating a mature and actively maintained library. Its primary differentiator is its ability to abstract away the intricacies of individual OAuth providers, offering a unified authentication experience through OneGraph's single GraphQL endpoint. This simplifies development by reducing the need to manage multiple API keys and authentication mechanisms for services like GitHub, Stripe, and others. It is specifically designed for browser environments, leveraging the global `window` object for its operations.
npm install onegraph-authVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize the OneGraphAuth client, check login status for GitHub, and initiate the OAuth login flow if the user is not authenticated. It also shows how to retrieve the necessary authorization headers after a successful login, suitable for use with a GraphQL client.
Ensure `OneGraphAuth` instances are only created and methods are called within a `useEffect` hook in React, or within `window.onload` in vanilla JavaScript, to guarantee a browser environment. For SSR, conditionally import or initialize the library client-side.
Always provide your `appId` during `OneGraphAuth` instantiation. It is recommended to load this from environment variables (e.g., `process.env.NEXT_PUBLIC_ONEGRAPH_APP_ID` in Next.js) and include a runtime check to ensure it's defined before initialization.
Instruct users to disable popup blockers for your domain, or provide clear UI feedback if a popup is blocked (e.g., by catching the promise rejection if the browser API allows detecting it, or by observing if `isLoggedIn` doesn't change after an expected login attempt).
For Apollo Client, use a `request` handler to dynamically set context headers, as shown in the README example: `request: (operation) => operation.setContext({headers: auth.authHeaders()})`. Alternatively, use `onegraph-apollo-client` which handles this automatically.Use ES Module import syntax: `import OneGraphAuth from 'onegraph-auth';`. Ensure your build configuration (e.g., `tsconfig.json`'s `module` field, Webpack/Rollup config) correctly handles ES Modules.
Wrap `OneGraphAuth` instantiation and method calls in client-side checks. For React, use `useEffect` or dynamic imports. For frameworks like Next.js, ensure components using `onegraph-auth` are only rendered client-side or explicitly wrap in `typeof window !== 'undefined'` checks.
This is a user-side issue. Provide clear instructions to users to allow popups from your domain. In some cases, frameworks might offer ways to detect if a popup was blocked, allowing for custom error messages or fallback UI.
Verify that `auth.login('service')` has been successfully completed and that `auth.authHeaders()` is correctly used to populate the `Authorization` header for all outgoing API requests. If using Apollo Client, ensure the `request` function dynamically calls `auth.authHeaders()` for each operation.