ZewstID Integration - Common Pitfalls Checklist

Use this when: Integration not working, mysterious errors, "it should work but doesn't"

🔍 Diagnostic Questions

Run through these in order:

1. SDK Version Check


npm list @zewstid/nextjs

Is it v0.4.1 or later?
- ❌ v0.1.x → Too old, missing account linking
- ❌ v0.2.x → Missing password reset
- ❌ v0.3.x → Missing bug fixes
- ❌ v0.4.0 → Has account linking endpoint bug
- ✅ v0.4.1+ → All features working

Fix if wrong:


npm install @zewstid/nextjs@latest --registry https://npm.zewstid.com/

2. npm Registry Check


npm config get @zewstid:registry

Does it show
https://npm.zewstid.com/
?
- ❌
  https://registry.npmjs.org/
  → Wrong registry!
- ✅
  https://npm.zewstid.com/
  → Correct

Fix if wrong:


npm config set @zewstid:registry https://npm.zewstid.com/
npm install @zewstid/nextjs@latest --registry https://npm.zewstid.com/

3. Environment Variables Check


cat .env.local | grep ZEWST

Must have:

NEXT_PUBLIC_ZEWSTID_API_URL=https://api.zewstid.com
NEXT_PUBLIC_ZEWSTID_CLIENT_ID=your-client-id

Common mistakes:


# ❌ Missing NEXT_PUBLIC_ prefix (won't work in browser)
ZEWSTID_API_URL=https://api.zewstid.com

# ✅ Correct
NEXT_PUBLIC_ZEWSTID_API_URL=https://api.zewstid.com

# ❌ Wrong URL
NEXT_PUBLIC_ZEWSTID_API_URL=https://id.zewst.com

# ✅ Correct
NEXT_PUBLIC_ZEWSTID_API_URL=https://api.zewstid.com

Fix: Add

NEXT_PUBLIC_

prefix and use

api.zewstid.com

4. OAuth Client Configuration

Check with admin:

Client ID exists in ZewstID
Callback URLs are configured correctly
Client has required permissions

Common callback URL mistakes:


// ❌ What you configure in ZewstID
http://localhost:3000/api/auth/callback

// ✅ What NextAuth actually uses
http://localhost:3000/api/auth/callback/zewstid
                                    ^^^^^^ Note the provider suffix!

5. API Endpoint Errors

404 "Endpoint not found"

Symptom: API calls return 404

Diagnose:


// Check what endpoint you're calling
console.log('Calling:', endpoint);

Common mistakes:


// ❌ v0.4.0 and earlier used wrong endpoint
GET /api/v1/auth/identities  // 404!

// ✅ v0.4.1+ uses correct endpoint
GET /api/v1/auth/link/identities  // Works!

Fix: Upgrade to v0.4.1

6. Account Linking Not Working

Symptoms:

Can't link Google to existing account
"User already exists" errors
Account linking UI shows nothing

Checklist:

Using SDK v0.4.1 or later?
User already signed in before linking?
Correct email for linking?
Provider not already linked?

Test it:


// 1. Check current identities
const { identities } = await zewstid.accountLinking.getLinkedIdentities();
console.log('Current:', identities);

// 2. Try to link
const response = await zewstid.accountLinking.initiate({
  email: user.email,
  provider: 'google',
  clientId: process.env.NEXT_PUBLIC_ZEWSTID_CLIENT_ID!,
});

console.log('Linking token:', response.linkingToken);

7. CORS Errors

Symptom: Browser console shows CORS errors

Diagnose:


// Open browser console, look for:
Access to fetch at 'https://api.zewstid.com' from origin 'http://localhost:3000' 
has been blocked by CORS policy

Fix:

API Gateway already allows CORS from all origins
If still seeing errors, check you're using correct API URL
Make sure you're not accidentally calling
id.zewst.com
instead of
api.zewstid.com

8. Session/Token Issues

Symptoms:

"Unauthorized" errors
Tokens expire immediately
Can't stay logged in

Check token validity:


const response = await zewstid.auth.signInWithPassword({...});

// Decode JWT (don't do in production, just for debugging)
const payload = JSON.parse(atob(response.accessToken.split('.')[1]));
console.log('Token expires:', new Date(payload.exp * 1000));
console.log('Issued at:', new Date(payload.iat * 1000));

Common issues:

Clock skew (server time != client time)
Token not being stored
Using expired refresh token

9. Rate Limiting

Symptom: "Too many requests" / 429 errors

What's happening:

IP-based: 10 requests per 15 minutes
Email-based (magic link/OTP): 5 requests per hour

Fix:

Wait for rate limit to reset
Don't spam authentication endpoints in development
Use a different email for testing

10. Import Errors

Symptoms:

"Module not found"
"Cannot find 'ZewstID'"
TypeScript errors

Check imports:


// ❌ Old SDK (v0.1.x)
import { ZewstAuth } from '@zewstid/nextjs';

// ✅ New SDK (v0.4.1)
import { ZewstID } from '@zewstid/nextjs';

// ❌ Wrong path
import { ZewstID } from '@zewstid/nextjs/dist';

// ✅ Correct
import { ZewstID } from '@zewstid/nextjs';

🚨 Emergency Debugging Checklist

If nothing above worked:


# 1. Clean install
rm -rf node_modules package-lock.json
npm install

# 2. Verify SDK
npm list @zewstid/nextjs
# Should show: @zewstid/nextjs@0.4.1

# 3. Check environment
cat .env.local

# 4. Test API directly
curl https://api.zewstid.com/health
# Should return: {"status":"ok"}

# 5. Check network
curl -v https://api.zewstid.com/api/v1/auth/link/identities
# Should return 401 (expected, we're not authenticated)
# Should NOT return 404

# 6. Verify Next.js can see variables
# Add to page:
console.log({
  apiUrl: process.env.NEXT_PUBLIC_ZEWSTID_API_URL,
  clientId: process.env.NEXT_PUBLIC_ZEWSTID_CLIENT_ID,
});
# Both should have values (not undefined)

📞 When to Ask for Help

Try checklist first, then ask for help if:

✅ Checked all items above
✅ SDK is v0.4.1
✅ Environment variables correct
✅ Can hit https://api.zewstid.com/health
❌ Still not working

Include in your help request:


SDK version: <run: npm list @zewstid/nextjs>
Error message: <full error from console>
What you're trying: <e.g., "Login with password">
Code snippet: <the exact code that's failing>
Network tab: <screenshot of failed API call>

✅ Success Checklist

Your integration is working if:

Last Updated: December 7, 2025
SDK Version: v0.4.1
Success Rate: 95% of issues resolved by this checklist

Was this page helpful?

Let us know how we can improve our documentation