External Auth

Use your own identity provider (Google, Firebase, Clerk, Auth0, Supabase, etc.) instead of MoonDB's built-in auth. MoonDB validates RS256-signed JWTs against the provider's JWKS endpoint.

How it works

1. Configure your provider's JWKS URL on the MoonDB project (once)
2. User logs in via your provider (Google, Clerk, etc.) in your frontend
3. Your frontend passes the JWT to MoonDB as Authorization: Bearer {token}
4. MoonDB validates the signature via JWKS and extracts the user ID from the sub claim

After this, all MoonDB access rules (authenticated, owner) work with the external user identity.

Setup

PUT /p/{id}/v1/auth-config
X-Admin-Key: sk_...

{
  "provider": "external",
  "jwks_url": "https://your-provider.com/.well-known/jwks.json",
  "user_id_claim": "sub",
  "audience": "your-provider-audience",
  "issuer": "https://your-issuer"
}

Important: audience must match the aud claim in your provider's JWTs (usually your OAuth client ID or project ID at the provider). If omitted, it defaults to your MoonDB project ID — which won't match external tokens.

Provider Examples

Google (Sign In with Google)

{
  "provider": "external",
  "jwks_url": "https://www.googleapis.com/oauth2/v3/certs",
  "user_id_claim": "sub",
  "audience": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
  "issuer": "https://accounts.google.com"
}

audience = your Google OAuth Client ID. Get it from the Google Cloud Console.

Firebase Auth

{
  "provider": "external",
  "jwks_url": "https://www.googleapis.com/service/v3/beta/jwk/securetoken@system.gserviceaccount.com",
  "user_id_claim": "sub",
  "audience": "YOUR_FIREBASE_PROJECT_ID",
  "issuer": "https://securetoken.google.com/YOUR_FIREBASE_PROJECT_ID"
}

audience and issuer both use your Firebase project ID (found in Firebase Console → Project Settings).

Clerk

{
  "provider": "external",
  "jwks_url": "https://YOUR_CLERK_DOMAIN/.well-known/jwks.json",
  "user_id_claim": "sub",
  "audience": "your-audience",
  "issuer": "https://YOUR_CLERK_DOMAIN"
}

Find your JWKS URL in the Clerk Dashboard → JWT Templates → JWKS endpoint.

Auth0

{
  "provider": "external",
  "jwks_url": "https://YOUR_TENANT.auth0.com/.well-known/jwks.json",
  "user_id_claim": "sub",
  "audience": "your-api-identifier",
  "issuer": "https://YOUR_TENANT.auth0.com/"
}

audience = the API Identifier from Auth0 Dashboard → Applications → APIs.

Supabase

{
  "provider": "external",
  "jwks_url": "https://YOUR_REF.supabase.co/auth/v1/.well-known/jwks.json",
  "user_id_claim": "sub",
  "audience": "authenticated",
  "issuer": "https://YOUR_REF.supabase.co/auth/v1"
}

Frontend Integration

// Example: Google Sign-In → MoonDB
const { credential } = googleResponse;  // Google ID token (JWT)

const res = await fetch(MOONDB_URL + '/api/posts', {
  headers: {
    'Authorization': 'Bearer ' + credential,
    'X-Public-Key': 'pk_...'
  }
});

Managing Config

# Read current config
GET /p/{id}/v1/auth-config  (X-Admin-Key: sk_...)

# Remove external auth (revert to built-in)
DELETE /p/{id}/v1/auth-config  (X-Admin-Key: sk_...)

Restrictions

• Only RS256 (RSA + SHA-256) JWTs are supported
• jwks_url must be https:// on a known IdP host: *.clerk.com, *.auth0.com, *.supabase.co, *.firebaseapp.com, *.googleapis.com, securetoken.google.com, *.amazoncognito.com, *.kinde.com, *.workos.com, *.stytch.com
• JWKS is cached for 1 hour — key rotations take up to 1h to propagate

Troubleshooting

Error	Cause	Fix
AUTH_BAD_AUDIENCE	audience in config doesn't match token's aud	Set audience to your OAuth client ID / Firebase project ID
AUTH_BAD_ISSUER	issuer in config doesn't match token's iss	Check your provider's issuer URL (include trailing slash if needed)
AUTH_UNSUPPORTED_ALG	Token uses HS256 or another algorithm	Configure your provider to issue RS256 tokens
AUTH_JWKS_FETCH_FAILED	JWKS URL unreachable or wrong format	Verify the URL returns a JSON {"keys": [...]} response
AUTH_NO_KEY	No matching key in JWKS for token's kid	Provider may have rotated keys — wait up to 1h for cache refresh
VALIDATION_JWKS_HOST	JWKS URL host not in allowlist	Use a supported provider or contact support