Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moca.network/llms.txt

Use this file to discover all available pages before exploring further.

If your app already authenticates users (via Firebase, Auth0, Supabase, or a custom system), you can bypass the AIR Kit login dialog and pass the authenticated user straight into an AIR Kit session. This is called Custom Auth (or BYO Auth).

​
How it works

  1. Your app authenticates the user through your own system.
  2. Your backend signs a Partner JWT containing the user’s email and partnerUserId.
  3. Your frontend passes that JWT to airService.login({ authToken }).
  4. AIR Kit creates or loads the user’s AIR Account, skipping the built-in login UI.
When an email is provided in the JWT, AIR Kit verifies it with a one-time password the first time. After that initial verification, subsequent logins are seamless.

​
Prerequisites

  • AIR Kit SDK installed and initialized. See Installation.
  • Partner JWT signing configured (RS256 or ES256).
  • The authenticated user’s email address available on your backend.

​
Step 1: Generate a Partner JWT on your backend

Include email and partnerUserId alongside partnerId: 
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");

function getAuthToken(user) {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    {
      partnerId: process.env.PARTNER_ID,
      email: user.email,
      partnerUserId: user.id,
      iat: now,
      exp: now + 5 * 60,
    },
    privateKey,
    { algorithm: "RS256", header: { kid: process.env.KEY_ID } }
  );
}

// Express example
app.get("/api/air-token", requireAuth, (req, res) => {
  const token = getAuthToken(req.user);
  res.json({ token });
});

​
Step 2: Fetch the token and log in on the frontend

const airService = new AirService();
await airService.init({ partnerId: "your-partner-id" });

const res = await fetch("/api/air-token");
const { token } = await res.json();

const loginResult = await airService.login({ authToken: token });
console.log("AIR Account address:", loginResult.abstractAccountAddress);
The user is now logged into AIR Kit without seeing any login dialog. Their AIR Account is tied to the email from your system.

​
Step 3: Use AIR Kit features normally

After login, all SDK methods work as usual — issue credentials, verify credentials, access smart accounts: 
if (airService.isLoggedIn) {
  const userInfo = await airService.getUserInfo();
  console.log("User:", userInfo);
}

​
JWT payload reference

{
  "partnerId": "your-partner-id",
  "email": "user@example.com",
  "partnerUserId": "usr_abc123",
  "exp": 1728973684,
  "iat": 1728970084
}
FieldRequiredDescription
partnerIdYesYour Partner ID
emailYes (for custom auth)The user’s verified email, used as their AIR Account identifier
partnerUserIdRecommendedYour internal user ID, persisted on the AIR Account for cross-referencing
expYesToken expiration (recommended: 5 minutes)

​
Next steps