Introduction

@kysoql/auth handles Salesforce OAuth separately from query building. Pick the flow that fits your application, get a Salesforce session, then pass the access token to @kysoql/rest or another Salesforce client.

For most applications, start with SalesforceAuth. It keeps the Salesforce login or site URL and client ID in one place, then exposes the supported flows as methods.

For a server-to-server integration that can protect a private key, JWT bearer is the usual starting point. It does not require an interactive login or a stored refresh token.

InstallCopy Anchor Link

pnpm add @kysoql/auth @kysoql/rest

Server-to-server with JWT bearerCopy Anchor Link

import { SalesforceAuth } from "@kysoql/auth";
import { createRestExecutor } from "@kysoql/rest";

const auth = new SalesforceAuth({
  loginUrl: "https://login.salesforce.com",
  clientId: "external-client-app-id",
});

export async function createSalesforceExecutor() {
  const authenticate = () =>
    auth.jwtBearer({
      username: "integration@example.com",
      privateKey: { type: "file", path: "./salesforce-auth-key.pem" },
    });

  let session = await authenticate();
  const instanceUrl = session.instanceUrl;

  return createRestExecutor({
    instanceUrl,
    accessToken: async ({ refresh }) => {
      if (refresh) {
        const next = await authenticate();

        if (next.instanceUrl !== instanceUrl) {
          throw new Error("Salesforce instance changed. Recreate the REST client.");
        }

        session = next;
      }

      return session.accessToken;
    },
  });
}

Keep the signing key server-side. Private keys use an explicit source object, so Kysoql never has to guess whether a string is a path or PEM content.

Choose the source that matches where your key lives:

• File: { type: "file", path }
• PEM string: { type: "pem", value }
• Web Crypto key: { type: "crypto-key", key }

The JWT bearer guide covers Salesforce setup and token renewal in more detail.

Choose another flowCopy Anchor Link

Use the authentication flow guide when your application needs interactive login, refresh tokens, client credentials, Experience Cloud identity, SAML, token exchange, or one of Salesforce's first-party application flows.

Salesforce's retiring username-password, user-agent, and hybrid user-agent flows are not implemented. Asset tokens are device identity tokens rather than general bearer sessions for SOQL REST calls.