Skip to main content

Integration Guide

Use the TypeScript SDK to add zero-knowledge authentication to your app.

Install​

npm install @azkey/sdk
# or
pnpm add @azkey/sdk

Initialize the AccountManager​

import { AccountManager } from '@azkey/sdk';

const accountManager = new AccountManager({
  googleClientId: process.env.GOOGLE_CLIENT_ID!,
  googleClientSecret: process.env.GOOGLE_CLIENT_SECRET,
  aztecRpcUrl: process.env.AZTEC_RPC_URL || 'http://localhost:8080',
  redirectUri: 'https://yourapp.com/oauth/callback',
});

Run the OAuth flow​

// Redirect the user
const authUrl = accountManager.getAuthUrl();
window.location.href = authUrl;

// In your callback route
const code = new URLSearchParams(window.location.search).get('code');
const authResult = await accountManager.exchangeCode(code!);

Create or recover an account​

const existing = await accountManager.accountExistsForIdentity(authResult);

let account;
if (existing) {
  account = await accountManager.recoverAccount(authResult, existing);
} else {
  account = await accountManager.createAccount(authResult);
}

console.log('Account address:', account.address);
console.log('Session owner:', account.sessionOwner);

Use the session owner for transactions​

The sessionOwner is an ephemeral public key authorized on the account contract. Use it to sign Aztec transactions in your app (with your preferred Aztec client setup).

Adding another identity provider​

The SDK is provider-agnostic. To add Apple (example):

  1. Implement AppleProvider similar to GoogleProvider (OAuth URLs, token exchange, JWT parsing, public key fetch).
  2. Extend AccountManager to accept 'apple' and instantiate the right provider.
  3. If the JWT format or signature changes, adjust the Noir circuit inputs accordingly.

Error handling tips​

  • OAuth code expired: re-initiate the login flow.
  • Failed to verify JWT: check the provider public keys and redirect URI.
  • Contract deployment failed: verify Aztec RPC availability and gas settings.
  • Account not found: run createAccount instead of recoverAccount.