KysoqlAuthentication flow guide
Choose the Salesforce authentication flow that fits a REST and SOQL integration.
@kysoql/auth covers the supported Salesforce OAuth and assertion flows that can
produce bearer sessions for REST API use. The SalesforceAuth class is the
primary application-facing API: configure the Salesforce URL and client ID once,
then choose the flow through a method. Start with JWT bearer for a typical
certificate-backed server-to-server integration, then choose another flow only
when the application architecture requires it.
| Flow | Typical use | Kysoql guide |
|---|---|---|
| JWT bearer | Server-to-server with an integration user and private key | JWT bearer |
| Web-server + PKCE | User-facing web application | Web-server + PKCE |
| Refresh token | Renew an authorized user session | Refresh token |
| Client credentials | Server-to-server with client ID/secret and configured integration user | Client credentials |
private_key_jwt | Authenticate a confidential OAuth client at supported token endpoints | Private-key client authentication |
| SAML bearer | Exchange a signed SAML 2.0 bearer assertion | SAML bearer |
| SAML assertion | Federate to the Salesforce API using the SAML assertion API flow | SAML assertion |
| Token exchange | Exchange a token from an identity provider for a Salesforce token | Token exchange |
| Device | CLI or constrained-input device authorization | Device flow |
| Hybrid web-server | Hybrid apps that need Salesforce web-session bridging | Hybrid web-server |
| Hybrid refresh | Renew a hybrid app session and web-session SIDs | Hybrid refresh |
| Authorization Code and Credentials | Headless Experience Cloud named-user or discovered-user login | Code and Credentials |
| Headless guest | Experience Cloud guest authorization with UVID context | Headless guest |
| First-party username-password | First-party headless login for private Experience Cloud clients | Username-password |
| First-party passwordless | Email/SMS OTP login for private Experience Cloud clients | Passwordless |
| First-party registration | Headless registration and OTP verification | Registration |
Common behavior
Token-endpoint helpers validate HTTPS Salesforce URLs, send form-encoded POST requests where Salesforce requires them, reject redirects, enforce bounded request timeouts, and validate bearer-token responses.
OAuth HTTP failures throw SalesforceOAuthError, exposing the HTTP status and
OAuth error code. Malformed successful responses throw
SalesforceOAuthResponseError.
For REST API usage, pass the returned instanceUrl and accessToken to
@kysoql/rest. Salesforce REST API accepts OAuth bearer tokens in the
Authorization header.