Authentication and token refresh

@kysoql/rest only needs a Salesforce instance URL and bearer token. @kysoql/auth is the companion package for obtaining and renewing those tokens.

Keeping authentication separate means the REST executor works the same way whether your application uses JWT bearer, refresh tokens, client credentials, an interactive login flow, or a session supplied by another system.

Use an existing access tokenCopy Anchor Link

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

export function executorForSession(instanceUrl: string, accessToken: string) {
  return createRestExecutor({ instanceUrl, accessToken, apiVersion: "65.0" });
}

Use the instance_url returned by Salesforce authentication rather than a generic login host. A static token is never refreshed automatically.

Use a renewable token providerCopy Anchor Link

Flows that issue refresh tokens can plug directly into the REST executor through storedRefreshToken():

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

export async function createRefreshingExecutor(refreshToken: string) {
  const auth = new SalesforceAuth({
    loginUrl: "https://example.my.salesforce.com",
    clientId: "oauth-client-id",
  });

  const sessionAuth = auth.storedRefreshToken({
    initialRefreshToken: refreshToken,
    refreshTokenStore: createMemoryRefreshTokenStore(),
  });

  const session = await sessionAuth.getSession();

  return createRestExecutor({
    instanceUrl: session.instanceUrl,
    accessToken: sessionAuth.accessTokenProvider,
  });
}

The REST client caches the provider's current token. If Salesforce returns 401 INVALID_SESSION_ID, it asks the provider for a refreshed token and replays that request once.

Concurrent requests on the same REST client share in-progress token acquisition and refresh work. If several application processes share a rotating refresh token in Redis, coordinate rotation across those processes with your normal distributed locking strategy.

Compatibility helpersCopy Anchor Link

@kysoql/rest still exports authenticateClientCredentials() and refreshAccessToken() for existing users. New authentication code should generally use SalesforceAuth, which keeps the full set of supported flows and token-storage behaviour in one package.

You do not need either package's authentication helpers if your application already has a valid Salesforce bearer token.

Keep credentials at the application boundaryCopy Anchor Link

Generated Salesforce types do not grant object, field, or record access. Salesforce applies the permissions of the identity behind the token.

Keep client secrets, private keys, refresh tokens, and production access tokens out of source code and logs. See security and production use and refresh-token storage.