Passkey SDK Kit (Mobile)

A modern JavaScript/TypeScript SDK for implementing passkey authentication in React Native mobile applications. This SDK provides a simple and secure way to register and authenticate users using passkeys.

Features

• 🔐 Secure Authentication: Uses passkey standards for secure authentication
• 📱 Mobile-First: Designed for React Native (Android/iOS)
• 🔧 Easy Integration: Simple API for quick implementation
• 📦 TypeScript Support: Full TypeScript definitions included
• 🚀 Lightweight: Minimal dependencies

📋 Table of Contents

1. Subscription & Setup
2. Installation
3. Platform Configuration
4. Quick Start
5. API Reference
6. Error Handling
7. Security Considerations

🔐 Subscription & Setup

Step 1: Subscribe to the SDK

To use the Passkey SDK, follow these steps:

1. Pay a small subscription fee.
2. Provide the following platform details:
   • Project Name
   • Platform URL
   • Android APK KeyHash
   • Apple TeamId
   • Android packageName
   • Android SHA-256 certificate fingerprints
3. After submitting these details, you will receive:
   • API Key – used to initialize the SDK instance on the client.
   • Secret Key – used on the backend to verify JWT tokens signed using the HS256 algorithm.

Step 2: Generate Required Keys

🔑 Generate Android APK KeyHash

For Debug Certificate:

keytool -exportcert -keystore <path_to_debug_keystore> -alias androiddebugkey -storepass android | openssl sha256 -binary | openssl base64

Replace <path_to_debug_keystore> with your actual path, e.g.:

~/your-project/android/app/debug.keystore

For Release Certificate:

keytool -exportcert -keystore <path_to_release_keystore> -alias <your_key_alias> -storepass <your_keystore_password> | openssl sha256 -binary | openssl base64

Replace the placeholders with your actual values:

• <path_to_release_keystore>: Path to your release keystore file
• <your_key_alias>: Your key alias
• <your_keystore_password>: Your keystore password

🔐 Generate SHA-256 Certificate Fingerprints

For Debug Certificate:

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

For Release Certificate:

keytool -list -v -keystore <path_to_your_release_keystore> -alias <your_key_alias>

Look for the "SHA256" fingerprint in the output.

📦 Installation

Step 3: Install Dependencies

npm install passkey-sdk-kit-mobile axios react-native-passkey

Note: You must also follow the setup instructions for react-native-passkey in your React Native project (linking, permissions, etc).

Step 4: Add Required Imports

Add these imports to your index.js file:

import 'react-native-get-random-values';
import { decode as atob } from 'base-64';

🛠️ Platform Configuration

Step 5: Android Configuration

Prerequisites:

• Minimum SDK Version: 24
• Ensure your React Native Android project is correctly set up.

Update android/app/build.gradle

dependencies {
    implementation 'com.google.android.gms:play-services-auth:20.7.0'
}

Modify AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.USE_FINGERPRINT" />
    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
    <application>
        <meta-data
            android:name="androidx.credentials.ENABLED"
            android:value="true" />
        <!-- Optional: Deep link for Passkey redirect -->
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data
                    android:scheme="https"
                    android:host="stage-api-internal-passkey.staging-host.com"
                    android:pathPrefix="/passkey" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Step 6: iOS Configuration

Update Entitlements File

Add the following to ios/<YourAppName>/<YourAppName>.entitlements:

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:stage-api-internal-passkey.staging-host.com</string>
        <string>applinks:stage-api-internal-passkey.staging-host.com</string>
    </array>
</dict>
</plist>

Purpose of Keys: | Key | Purpose | | ----------------- | -------------------------------------------------------------------------- | | webcredentials: | Enables Passkey support via iCloud Keychain for secure credential storage. | | applinks: | Supports Universal Links to redirect from Safari to the app. |

🚀 Quick Start

Step 7: Initialize the SDK

import { PasskeySDKMobile } from 'passkey-sdk-kit-mobile';

// Initialize with your API key
const sdk = new PasskeySDKMobile('your-api-key-here');

// Initialize the SDK (required before using other methods)
await sdk.init();

Step 8: Register a User's Passkey

// User information
const userInfo = {
    email: '[email protected]',
    name: 'John Doe',
};

// Register passkey for a user
try {
    const result = await sdk.registerPasskey(
        'user-id-123', // Unique user ID (string, will be base64url-encoded internally)
        userInfo       // User information
    );
    console.log('Passkey registered successfully:', result);
} catch (error) {
    console.error('Registration failed:', error);
}

Step 9: Authenticate with Passkey

// Authenticate user with passkey
try {
    const result = await sdk.loginWithPasskey();
    // result.token contains a JWT token with the uId in the payload
    console.log('Authentication successful:', result);
} catch (error) {
    console.error('Authentication failed:', error);
}

Step 10: Backend JWT Verification

const jwt = require('jsonwebtoken');

const token = '...'; // JWT from SDK login
const secret = 'YOUR_SECRET_KEY'; // secret key provided at subscription

try {
  const payload = jwt.verify(token, secret, { algorithms: ['HS256'] });
  const uId = payload.uId;
  // Proceed with user session logic
} catch (err) {
  // Invalid token
}

📚 API Reference

Constructor

new PasskeySDKMobile(apiKey: string)

• apiKey (string): Your API key for authentication

Methods

init()

Initializes the SDK and fetches merchant configuration. Must be called before using other methods.

await sdk.init();

registerPasskey(uId, userInfo)

Registers a new passkey for a user.

Parameters:

• uId (string): Unique user identifier (will be base64url-encoded internally)
• userInfo (object): User information object
  • email (string): User's email address
  • name (string): User's display name

Returns: Promise with registration result

loginWithPasskey()

Authenticates a user using their passkey.

Returns: Promise with authentication result (token property contains JWT with uId in payload)

checkPasskeyStatus(uId)

Checks if a user has a passkey registered.

Parameters:

• uId (string): Unique user identifier

Returns: Promise with passkey status

deletePasskey(uId)

Deletes a user's passkey.

Parameters:

• uId (string): Unique user identifier

Returns: Promise with deletion result

TypeScript Support

import { PasskeySDKMobile, UserInfo } from 'passkey-sdk-kit-mobile';

const userInfo: UserInfo = {
    email: '[email protected]',
    name: 'John Doe',
};

⚠️ Error Handling

The SDK methods may throw errors in various scenarios:

try {
    const result = await sdk.registerPasskey(uId, userInfo);
} catch (error) {
    if (error.response) {
        // Server responded with error status
        console.error('Server error:', error.response.data);
    } else if (error.request) {
        // Network error
        console.error('Network error:', error.message);
    } else {
        // Other error
        console.error('Error:', error.message);
    }
}

🔒 Security Considerations

• Always use HTTPS in production
• Validate all user inputs
• Store API keys securely
• Follow security best practices for your application
• Implement proper session management
• Handle deep links securely in your app's navigation logic
• Implement biometric fallback for devices without biometric support

📋 Platform Requirements

• React Native (Android/iOS)
• react-native-passkey properly linked and configured
• Modern JavaScript features (ES2020+)

🌐 Web Support

If you want to use the passkey for web applications as well, you can use the same API key with the web SDK:

npm install passkey-sdk-kit

For more information and documentation, visit: https://www.npmjs.com/package/passkey-sdk-kit

📄 License

MIT License - see LICENSE file for details.