Bring Your Own Authentication

Integrate your existing authentication provider and add smart wallet functionality to your app without changing your users' login experience. Smart Wallets supports JWT-based and OIDC-compliant authentication providers.

Prerequisites

Before implementing JWT authentication, verify that your authentication system meets these requirements:

1. OIDC Compliance

Your authentication system must be OpenID Connect (OIDC) compliant and capable of issuing JWT tokens.

2. Required Endpoints

OpenID Connect Discovery Endpoint

Host a discovery endpoint at: <YOUR_API_DOMAIN>/.well-known/openid-configuration

The response must include these required fields from the OpenID spec:

{
  "issuer": "<YOUR_API_DOMAIN>",
  "jwks_uri": "<YOUR_JWKS_ENDPOINT_URL>",
  "id_token_signing_alg_values_supported": ["RS256"],
  "authorization_endpoint": "<YOUR_AUTH_ENDPOINT>",
  "response_types_supported": ["<YOUR_SUPPORTED_RESPONSE_TYPE>"],
  "subject_types_supported": ["<YOUR_SUPPORTED_SUBJECT_TYPE>"]
}

Field explanations:

• issuer: Your API domain (must match the iss claim in your JWTs)
• jwks_uri: Endpoint URL where the JWT public key can be retrieved for verification
• id_token_signing_alg_values_supported: Must include "RS256" algorithm

3. JWT Structure Requirements

JWT Header Requirements

Your JWT header must include:

Important: The kid field in the JWT header must correspond to a key identifier from your JWKS endpoint to enable proper key lookup during token verification.

JWT Payload Requirements

Your JWTs must contain these claims:

Important: The nonce claim must be toHex(sha256(targetPublicKey)) without the leading 0x.

4. Audience Claim

The aud claim must be set to the audience ID provided in your Smart Wallet settings. Obtain the audience claim from the dashboard.

Implementation Guide

npm install @account-kit/signer @account-kit/react

import { AlchemySignerWebClient } from "@account-kit/signer";
import { sha256, stringToBytes } from 'viem'
 
const client = new AlchemySignerWebClient({
  connection: {
    apiKey: "your-api-key",
  },
  iframeConfig: {
    iframeContainerId: "signer-iframe-container",
  },
});
 
// Generate the target public key
const targetPublicKey = await client.targetPublicKey();
 
// Use this in your JWT's nonce claim
const nonce = sha256(stringToBytes(targetPublicKey)).slice(2)

import { useAuthenticate } from "@account-kit/react";
 
// Inside your component
const { authenticate, isPending } = useAuthenticate();
 
const handleJwtAuth = async (jwt: string) => {
  try {
    await authenticate({
      type: "custom-jwt",
      jwt // Your generated JWT with required claims
    });
  } catch (error) {
    console.error("Authentication failed:", error);
  }
};

import { useSignerStatus, useUser } from "@account-kit/react";
 
const MyComponent = () => {
  const { isConnected } = useSignerStatus();
  const user = useUser();
 
  if (isConnected && user) {
    return (
      <div>
        <p>Welcome, {user.email}!</p>
        <p>Wallet Address: {user.address}</p>
      </div>
    );
  }
 
  return <div>Not authenticated</div>;
};

{
  "jwt": "eyJhbGciOiJSUzI1NiJ9...", // Your base64 encoded JWT
  "targetPublicKey": "0x1234...",
}

{
  "isSignup": false,
  "credentialBundle": "encrypted-credential-bundle",
  "orgId": "organization-id"
}

{
  "jwt": "eyJhbGciOiJSUzI1NiJ9...",
}

{
  "isSignup": true,
  "userId": "alchemy-user-id",
  "address": "0xabcdef...", // EOA signer address
  "solanaAddress": "5Gv7...", // Solana address (if applicable)
  "orgId": "organization-id"
}

Architecture Overview

The JWT authentication flow works as follows:

1. User Authentication: User logs into your existing auth system
2. JWT Generation: Your backend generates a JWT with required claims
3. Submit JWT: Frontend submits JWT to the auth endpoint
4. Verification: The JWT is verified using your JWKS endpoint
5. Wallet Access: User gains access to their smart wallet

sequenceDiagram
    participant User
    participant YourApp as Your Application
    participant YourAuth as Your Auth System
    participant Alchemy as Alchemy API
 
    User->>YourApp: Login request
    YourApp->>YourAuth: Authenticate user
    YourAuth->>YourApp: Return JWT
    YourApp->>Alchemy: Submit JWT (/v1/auth-jwt)
    Alchemy->>YourApp: Verify JWT and return credentials/wallet info
    YourApp->>User: Wallet ready

Testing and Validation

JWT Validation Tool

Use jwt.io to decode and validate your JWT structure before integration.

Required Claims Checklist

• iss matches your OpenID config issuer
• sub contains unique user identifier
• aud contains your Alchemy-provided audience ID
• nonce or tknonce contains toHex(sha256(targetPublicKey)) without 0x
• JWT is signed with RS256 algorithm

Integration Testing

1. Verify your .well-known/openid-configuration endpoint is accessible
2. Test JWKS endpoint returns valid public keys
3. Validate JWT signature verification works
4. Test complete authentication flow with sample users

Next Steps

Sending transactions

Once your users have been authenticated, start sending transactions.

Sponsor gas for transactions

Start sponsoring gas fees for transactions via the Gas Manager.