Affinidi Auth SDK Kernel

1.9.0 verified Fri May 01 auth: no javascript

The Affinidi Auth SDK Kernel is a foundational authentication library for building decentralized identity solutions on the Affinidi platform. Current stable version is 1.9.0, with monthly releases following semantic versioning. It provides secure token management, cryptographic operations, and authentication flow orchestration for React and React Native applications. Unlike generic auth SDKs, it is tightly integrated with Affinidi's decentralized identity protocols and includes built-in key management. Ships TypeScript types and requires react and react-native as peer dependencies.

Common errors

error Module not found: Can't resolve '@affinidi/affinidi-auth-sdk-kernel' ↓

cause Peer dependencies (react, react-native) not installed or misconfigured module resolution

fix

Run 'npm install react react-native' and ensure bundler config resolves node_modules correctly.

error TypeError: Cannot read properties of undefined (reading 'login') ↓

cause useAuth() called outside of AuthProvider context

fix

Wrap the component with <AuthProvider> and ensure useAuth() is used inside the provider tree.

error Invariant Violation: Native module cannot be null ↓

cause React Native native module not linked

fix

Run 'npx react-native link @affinidi/affinidi-auth-sdk-kernel' or rebuild the app.

Warnings

breaking v1.0.0-rc.1 introduced a breaking change: AuthConfig interface renamed old 'clientSecret' to 'clientId' ↓

fix Replace 'clientSecret' with 'clientId' in config objects.

deprecated The 'AuthProvider' component's 'onError' prop is deprecated; use error handling via useAuth errors ↓

fix Migrate to try-catch around login() or handle errors from useAuth().

gotcha React Native requires linking the native module; auto-linking may fail in older RN versions ↓

fix Run 'npx react-native link @affinidi/affinidi-auth-sdk-kernel' for RN <0.60.

gotcha Token refresh silently fails if the refresh token is expired; no automatic refresh ↓

fix Handle 401 errors and re-initiate login flow.

Install

npm install affinidi-auth-sdk-kernel

yarn add affinidi-auth-sdk-kernel

pnpm add affinidi-auth-sdk-kernel

Imports

AffinidiAuth

wrong

const AffinidiAuth = require('@affinidi/affinidi-auth-sdk-kernel')

correct

import { AffinidiAuth } from '@affinidi/affinidi-auth-sdk-kernel'

ESM-only since v1, also supports named exports.

AuthConfig

wrong

import { AuthConfig } from '@affinidi/affinidi-auth-sdk-kernel'

correct

import type { AuthConfig } from '@affinidi/affinidi-auth-sdk-kernel'

AuthConfig is a TypeScript interface, import as type to avoid runtime errors.

AuthProvider

wrong

import AuthProvider from '@affinidi/affinidi-auth-sdk-kernel'

correct

import { AuthProvider } from '@affinidi/affinidi-auth-sdk-kernel'

AuthProvider is a named export, not default.

useAuth

wrong

import { useAuth } from '@affinidi/affinidi-auth-sdk-kernel'

correct

import { useAuth } from '@affinidi/affinidi-auth-sdk-kernel'

Hook for React, ensure react and react-native peer deps are installed.

Quickstart

Sets up Affinidi authentication with React, including configuration, provider, and login button using hooks.

import { AffinidiAuth, AuthProvider, useAuth } from '@affinidi/affinidi-auth-sdk-kernel';
import React from 'react';

const config = {
  clientId: process.env.AFFINIDI_CLIENT_ID ?? '',
  redirectUri: 'myapp://callback',
};

function App() {
  return (
    <AuthProvider config={config}>
      <LoginButton />
    </AuthProvider>
  );
}

function LoginButton() {
  const { login, isAuthenticated, user } = useAuth();
  return (
    <button onClick={() => login()}>
      {isAuthenticated ? `Hello ${user.name}` : 'Sign in with Affinidi'}
    </button>
  );
}

export default App;