Amal Chandran•3w ago

Call convex from a Node.js backend using service authentication

Hi, I need to call Convex from a Node.js backend using service authentication (per https://docs.convex.dev/auth#service-authentication). What's the recommended way to use the admin key in the Node.js client? Do I have to pass it as an argument to every query/mutation, or can I set it once when initializing the client to avoid boilerplate? I also noticed the internal setAdminAuth function. Is that intended for this use case? I've identified a few potential approaches: Using convex-better-auth: Generate an admin API key, use it to fetch a session token, and set that token in the Node.js client. (since im already using https://github.com/get-convex/better-auth) Using Custom JWTs: Configure custom JWT authentication as per the docs, generate a long-lived token for my service, and pass it using setAuth(). Static Key (Less Ideal): Pass the CONVEX_API_KEY as an argument to every individual query/mutation, which seems verbose.

Authentication | Convex Developer Hub

Add authentication to your Convex app.

6 Replies

Convex Bot•3w ago

Thanks for posting in <#1088161997662724167>. Reminder: If you have a Convex Pro account, use the Convex Dashboard to file support tickets. - Provide context: What are you trying to achieve, what is the end-user interaction, what are you seeing? (full error message, command output, etc.) - Use search.convex.dev to search Docs, Stack, and Discord all at once. - Additionally, you can post your questions in the Convex Community's <#1228095053885476985> channel to receive a response from AI. - Avoid tagging staff unless specifically instructed. Thank you!

erquhart•2w ago

Service authentication doc is just saying to set up a shared secret, which would be passed in the server-to-server call and compared in your Convex function. There aren't any service authentication api's to support this, just a pattern.

Amal ChandranOP•2w ago

Ok I guess using custom jwt we can avoid passing the shared secret everytime

Amal ChandranOP•2w ago

https://docs.convex.dev/auth/advanced/custom-jwt

Custom JWT Provider | Convex Developer Hub

Configure Convex to work with custom JWT providers that don't implement full OIDC protocol, including setup and client-side integration.

Amal ChandranOP•2w ago

Will generate jwt and pass it as auth header and make use of ctx.auth.getUserIdentity(); external service logic

import { api } from "@backend/convex/_generated/api";
import { ConvexHttpClient } from "convex/browser";
import { SignJWT, importPKCS8 } from "jose";

/**
 * Generate a new admin JWT token using RS256
 * Loads the private key from INVOKER_JWT environment variable
 */
async function generateAdminToken() {
  const now = Math.floor(Date.now() / 1000);
  const expiry = now + 24 * 60 * 60; // 24 hours from now

  // Load private key and kid from environment variable
  if (!process.env.INVOKER_JWT) {
    throw new Error(
      "INVOKER_JWT environment variable not found! Set it with the generated key data."
    );
  }

  const keyData = JSON.parse(
    Buffer.from(process.env.INVOKER_JWT, "base64").toString("utf-8")
  );
  const { privateKeyPem, kid } = keyData;

  const privateKey = await importPKCS8(privateKeyPem, "RS256");

  const jwt = await new SignJWT({
    // Custom claims
    sub: "console-user", // subject (user ID)
    aud: "console-user", // audience
    iss: "https://console.app.com", // issuer
    exp: expiry, // expiration time
    iat: now, // issued at
  })
    .setProtectedHeader({ alg: "RS256", typ: "JWT", kid })
    .sign(privateKey);

  return jwt;
}

async function main() {
 
  const jwtToken = await generateAdminToken();
 
  // Configure ConvexHttpClient with JWT authentication
  const client = new ConvexHttpClient("https://********.convex.cloud", {
    auth: jwtToken,
  });

  console.log("Convex client configured with JWT authentication");

  // Example: Use the client to make queries
  const result = await client.query(api.emails.getEmails, {});

  console.log(result);
}

main();

import { api } from "@backend/convex/_generated/api";
import { ConvexHttpClient } from "convex/browser";
import { SignJWT, importPKCS8 } from "jose";

/**
 * Generate a new admin JWT token using RS256
 * Loads the private key from INVOKER_JWT environment variable
 */
async function generateAdminToken() {
  const now = Math.floor(Date.now() / 1000);
  const expiry = now + 24 * 60 * 60; // 24 hours from now

  // Load private key and kid from environment variable
  if (!process.env.INVOKER_JWT) {
    throw new Error(
      "INVOKER_JWT environment variable not found! Set it with the generated key data."
    );
  }

  const keyData = JSON.parse(
    Buffer.from(process.env.INVOKER_JWT, "base64").toString("utf-8")
  );
  const { privateKeyPem, kid } = keyData;

  const privateKey = await importPKCS8(privateKeyPem, "RS256");

  const jwt = await new SignJWT({
    // Custom claims
    sub: "console-user", // subject (user ID)
    aud: "console-user", // audience
    iss: "https://console.app.com", // issuer
    exp: expiry, // expiration time
    iat: now, // issued at
  })
    .setProtectedHeader({ alg: "RS256", typ: "JWT", kid })
    .sign(privateKey);

  return jwt;
}

async function main() {
 
  const jwtToken = await generateAdminToken();
 
  // Configure ConvexHttpClient with JWT authentication
  const client = new ConvexHttpClient("https://********.convex.cloud", {
    auth: jwtToken,
  });

  console.log("Convex client configured with JWT authentication");

  // Example: Use the client to make queries
  const result = await client.query(api.emails.getEmails, {});

  console.log(result);
}

main();

convex/auth.config.ts

import { AuthConfig } from "convex/server";

export default {
  providers: [
 
    {
      type: "customJwt" as const,
      applicationID: "console-user",
      issuer: "https://console.app.com",
      jwks: process.env.CONVEX_JWKS_DATA_URI!,
      algorithm: "RS256" as const,
    },
  ],
} satisfies AuthConfig;

import { AuthConfig } from "convex/server";

export default {
  providers: [
 
    {
      type: "customJwt" as const,
      applicationID: "console-user",
      issuer: "https://console.app.com",
      jwks: process.env.CONVEX_JWKS_DATA_URI!,
      algorithm: "RS256" as const,
    },
  ],
} satisfies AuthConfig;

script to generate static keys that needs to be set as envs

erquhart•2w ago

If your server to server stuff is always on behalf of an authenticated user, regular auth works for sure

Call convex from a Node.js backend using service authentication

Did you find this page helpful?