Bring Your Own Authentication

Integrate your existing authentication provider and add smart wallet functionality to your app without changing your users' login experience. We support 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 Alchemy can retrieve the JWT public key 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 your Alchemy-provided audience ID. You can obtain the audience claim from your Smart Wallet settings in the Alchemy 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 to Alchemy: Frontend submits JWT to Alchemy's auth endpoint
4. Verification: Alchemy verifies JWT 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 a User Operation

Once your users have been authenticated, you can start sending transactions.

Sponsor Gas for a User Operation

Start sponsoring gas fees for transactions via the Gas Manager.