Xumm OAuth2 PKCE Client SDK

Common errors

• Error: Missing API Key

  cause The `XummPkce` constructor was called without a valid Xumm API key (UUID v4 string) or with an invalid one.
  fix Provide a valid Xumm API key (UUID v4 format) as the first argument to the `XummPkce` constructor: `new XummPkce('your-api-key-uuidv4', { ... });`

• redirect_uri_mismatch

  cause The `redirectUrl` configured in the `XummPkce` constructor (or its default `document.location.href`) does not exactly match the `redirectUrl` registered for your application in the Xumm Developer Console.
  fix Verify that the `redirectUrl` option passed to `XummPkce` precisely matches the redirect URL configured for your application in the Xumm Developer Console. Pay close attention to trailing slashes, subdomains, and protocols (http/https).

• ReferenceError: XummPkce is not defined

  cause Occurs when attempting to use `XummPkce` in a browser environment without properly loading the library via a script tag, or when using CommonJS `require` syntax in an ESM-only context.
  fix For browser usage without a bundler, ensure `<script src="https://xumm.app/assets/cdn/xumm-oauth2-pkce.min.js"></script>` is loaded before your script attempts to use `XummPkce`. For module-based projects, use `import { XummPkce } from 'xumm-oauth2-pkce';` and ensure your bundler/runtime supports ESM.

• Error: User cancelled authorization

  cause The user explicitly cancelled the authentication flow in the Xumm app, closed the authorization window/tab, or denied the authorization request.
  fix Handle this gracefully in your application's error callback (e.g., `sdk.on('error', (err) => { /* display message to user */ })`). This is an expected user action and not typically a technical fault, so clear any pending UI states.

Warnings

• gotcha Prioritize the event-based API (`.on('success', ...)`) over the promise-based (`.authorize().then(...)`) for future compatibility, as explicitly recommended by the library maintainers. The promise will resolve, but state changes are best observed via events.
  Fix: Refactor promise-based authorization logic to use the event-driven approach where possible, listening for `success`, `retrieved`, and `error` events to manage application state.
• gotcha Enabling the `implicit` option (setting `implicit: true` in `XummPkceOptions`) reduces security by allowing cross-browser sign-in without a fresh PKCE challenge, making it susceptible to some attack vectors. Only use if absolutely necessary and fully understand the implications.
  Fix: Avoid setting `implicit: true` unless there's a specific, understood requirement for legacy cross-browser sign-in support. Stick to the default `implicit: false` for enhanced security.
• gotcha The `redirectUrl` option defaults to `document.location.href`. If your application navigates away from the root path or uses complex routing that changes `document.location.href`, ensure this URL is explicitly set in the constructor and correctly configured in both the Xumm app and your constructor to prevent authorization flow failures.
  Fix: Always explicitly set `redirectUrl` in the `XummPkce` constructor to match the exact URL Xumm should redirect back to after authorization, and ensure this precisely matches your Xumm application's configuration in the Xumm Developer Console.

Install

• npm install xumm-oauth2-pkce npm
• yarn add xumm-oauth2-pkce yarn
• pnpm add xumm-oauth2-pkce pnpm

Imports

• XummPkce
  wrong:

  const XummPkce = require('xumm-oauth2-pkce')

  correct:

  import { XummPkce } from 'xumm-oauth2-pkce'

  The package is primarily designed for ESM consumption. While UMD builds are available for browsers via CDN, direct Node.js usage should favor ESM imports. It is a named export, not a default export.
• XummPkceOptions

  import type { XummPkceOptions } from 'xumm-oauth2-pkce'

  This type definition specifies the available options for the `XummPkce` constructor. Importing types separately is good practice in TypeScript.

Quickstart

This quickstart demonstrates how to initialize `XummPkce`, handle authentication events (success, retrieval, errors), and manage user login/logout state within a simple browser application. It uses both event listeners and `authorize()` for interactive authentication.

import { XummPkce } from 'xumm-oauth2-pkce';

// Replace with your actual Xumm API key or load from environment
const XUMM_API_KEY = process.env.XUMM_API_KEY ?? 'your-xumm-api-key-uuidv4';

const xumm = new XummPkce(XUMM_API_KEY);

const handleAuthResult = async () => {
  const state = await xumm.state();
  if (state && state.me) {
    const { sdk, me } = state;
    console.log("Successfully authenticated with Xumm!");
    console.log("User account:", me.account);
    console.log("Xumm SDK instance:", sdk); // This is an instance of xumm-sdk
    document.getElementById('auth-status')!.innerText = `Authenticated as ${me.account}`;
    document.getElementById('auth-button')!.innerText = 'Logout';
  } else {
    console.log("Not authenticated.");
    document.getElementById('auth-status')!.innerText = 'Not authenticated.';
    document.getElementById('auth-button')!.innerText = 'Sign in with Xumm';
  }
};

// Listen for retrieved session (e.g., after page refresh or mobile redirect)
xumm.on("retrieved", handleAuthResult);
// Listen for new successful authentication
xumm.on("success", handleAuthResult);
// Listen for errors
xumm.on("error", (error) => {
  console.error("Xumm authentication error:", error);
  document.getElementById('auth-status')!.innerText = `Authentication failed: ${error.message}`;
  xumm.logout(); // Clear any partial state
});

// Check authentication status on page load and set up interaction
document.addEventListener('DOMContentLoaded', async () => {
  document.body.innerHTML = `
    <div id="app" style="font-family: sans-serif; padding: 20px;">
      <h1>Xumm PKCE Auth Demo</h1>
      <p id="auth-status">Checking authentication status...</p>
      <button id="auth-button">Loading...</button>
    </div>
  `;

  document.getElementById("auth-button")!.onclick = async () => {
    const currentState = await xumm.state();
    if (currentState && currentState.me) {
      await xumm.logout();
      console.log("Logged out.");
    } else {
      console.log("Initiating Xumm authorization...");
      // For a new sign-in, the authorize() call will redirect or open a popup.
      // The 'success' event will handle the result.
      await xumm.authorize();
    }
    handleAuthResult(); // Update button and status immediately after action
  };

  handleAuthResult(); // Initial check
});