Authentication
kalam-link models auth as a tagged union with type-safe constructors.
Auth modes
import { Auth } from 'kalam-link';
Auth.basic('username', 'password'); // { type: 'basic', username, password }
Auth.jwt('<token>'); // { type: 'jwt', token }
Auth.none(); // { type: 'none' }authProvider — recommended
Use authProvider instead of a static auth value. It is an async callback
invoked before every (re-)connection, so tokens refresh transparently
without any extra wiring on your end.
import { createClient, Auth, type AuthProvider } from 'kalam-link';
const authProvider: AuthProvider = async () => {
const token = await myApp.getOrRefreshJwt(); // your token store
return Auth.jwt(token);
};
const client = createClient({
url: 'http://localhost:8080',
authProvider,
});
await client.connect();Why authProvider?
Static auth | authProvider | |
|---|---|---|
| Token refresh on reconnect | ❌ uses original token | ✅ always calls your callback |
| Works with OAuth / SSO | ❌ | ✅ |
| Works with API-key rotation | ❌ | ✅ |
With Basic auth bootstrap
If you need to log in first to get a JWT, do it inside the provider:
const authProvider: AuthProvider = async () => {
// Fetch a fresh JWT from your token endpoint
const res = await fetch('/api/auth/token');
const { access_token } = await res.json();
return Auth.jwt(access_token);
};Static auth
Static auth is supported and is the simplest way to get started. Use it when:
- you’re using long-lived credentials (dev Basic auth, service JWT)
- you don’t have a token refresh flow
If your credentials can expire, prefer authProvider so reconnects always use a fresh token.
// Static JWT auth
const client = createClient({
url: 'http://localhost:8080',
auth: Auth.jwt('<JWT_TOKEN>'),
});When you later add refresh logic, migrate to authProvider:
// ✅ Preferred
const client = createClient({
url: 'http://localhost:8080',
authProvider: async () => Auth.jwt(await getToken()),
});Basic → JWT login upgrade
login() requires the client to have been initialised with Auth.basic. It
calls /v1/api/auth/login and updates the internal auth to the returned JWT.
const client = createClient({
url: 'http://localhost:8080',
auth: Auth.basic('alice', 'Secret123!'),
});
const login = await client.login();
console.log(login.access_token, login.refresh_token);
// client auth is now JWT internallyauthProvider return type guidance
authProvider should return Auth.jwt(...) (or Auth.none() for anonymous/local dev).
Avoid returning Auth.basic(...) from the provider — Basic credentials are meant for the one-time login() upgrade flow.
Refresh token
const refreshed = await client.refreshToken('<refresh_token>');
console.log(refreshed.access_token);refreshToken() updates the internal auth to the new JWT token.
Auth helpers
import {
buildAuthHeader,
encodeBasicAuth,
isBasicAuth,
isJwtAuth,
isNoAuth,
isAuthenticated,
} from 'kalam-link';buildAuthHeader() returns:
- basic →
Basic <base64(username:password)> - jwt →
Bearer <token> - none →
undefined
Used internally by queryWithFiles() for multipart uploads.