JavaScript core client

@axowl/sdk-core is the client that @axowl/sdk (React) is built on. It has no framework dependency, so it is the one to use anywhere React is not: plain TypeScript, Vue, Svelte, or a Blazor WebAssembly app loading it as a wwwroot/js interop module.

npm install @axowl/sdk-core

The registry page shows the current version — see SDK packages.

Create the client

import { AxowlClient } from '@axowl/sdk-core';

const client = new AxowlClient({
  orgSlug:  'my-org',
  clientId: 'client_…',
  baseUrl:  'https://api.axowl.com',   // test environment: https://testapi.axowl.com
});

Option	Required	Default	What it is
orgSlug	✅	—	Your organization’s slug (the {slug} in dashboard URLs).
clientId	✅	—	The application’s client key (client_…, from Applications in the dashboard). Every public call goes to /api/public/apps/{clientId}/….
baseUrl	—	https://auth.axowl.com	The Axowl API host. Set it explicitly: https://api.axowl.com for live apps, https://testapi.axowl.com for the test environment. The built-in default is not the same host the backend SDKs default to (https://api.axowl.com), so leaving it out can send the browser and your server to different hosts.
hostedLoginUrl	—	https://login.axowl.com	The hosted login portal of the same environment as baseUrl (@axowl/sdk-core 0.3.6+). Test environment: https://login.test.axowl.com. <SignIn> uses it for “Continue with Axowl account”.
tokenStorage	—	'localStorage'	Where the end-user JWT is kept: 'localStorage', 'sessionStorage' or 'memory' ('cookie' is treated as 'memory'). Outside a browser the client always uses memory.
autoRefresh	—	true	Refresh the access token before it expires.
refreshThresholdSeconds	—	60	How early (seconds before expiry) a refresh is due.
requestTimeoutMs	—	15000	Per-request timeout for every call the client makes. 0 turns it off.

Finish a hosted sign-in — exchangeSessionCode

With hosted login you send the person to https://login.axowl.com/login/{clientKey}?redirect_url=…. After they sign in they come back to your redirect_url with ?code=<one-time code>. Trade that code for the end-user JWT:

const url  = new URL(location.href);
const code = url.searchParams.get('code');
if (code) {
  await client.exchangeSessionCode(code);   // stores the JWT
  url.searchParams.delete('code');
  history.replaceState(null, '', url);      // keep the used code out of the address bar
}

exchangeSessionCode(code) calls POST /api/public/apps/{clientId}/auth/session/exchange and stores the returned token the same way every other sign-in does. The code is single-use and short-lived: a used or expired code is answered 401 and fails with AuthenticationError; an empty code is answered 400 and fails with AxowlError. Nothing is stored in either case.

Tokens — getTokenManager()

const tokens = client.getTokenManager();

tokens.isAuthenticated();   // true while a non-expired access token is stored
tokens.getAccessToken();    // the end-user JWT, or null

Send the access token to your own API as Authorization: Bearer <token> and verify it there with the backend SDK for your runtime (@axowl/sdk-backend, Axowl.Sdk.Identity.Client, axowl-sdk for Python, com.axowl:axowl-sdk for Java) — see SDK overview. The browser holding a token is not proof of anything to your server; the signature check is.

The signed-in person — getUser()

const user = await client.getUser();
// { isAuthenticated: true, name: 'Jane Doe', email: '[email protected]', ... }

getUser() sends the stored token to GET /api/auth/user, which answers from the token’s claims (name, email, isAuthenticated). With no token it throws AuthenticationError without making a request.

Sign out — logout()

await client.logout();                                        // revoke and clear
await client.logout({ returnUrl: 'https://example.com/' });   // revoke, clear, then navigate there

logout() calls POST /api/public/apps/{clientId}/auth/logout, which revokes the end-user session, and clears the stored tokens even if that call fails. returnUrl must be listed exactly under Dashboard → Application → Authentication → post-logout return URLs; the server then answers with redirectUrl and, in a browser, the client navigates there. A URL that is not listed is refused with RETURN_URL_NOT_ALLOWED (AxowlError, statusCode 400): the session is not revoked at Axowl, but the client has already cleared its stored tokens.

Errors

Error	When
AxowlError	The API answered with a non-2xx status. statusCode holds the HTTP status; message holds the response body.
AuthenticationError (extends AxowlError)	A call that needs a token ran without one, or the API answered 401 — the stored tokens are cleared.
NetworkError	The request did not complete — offline, DNS, or requestTimeoutMs elapsed.

Related

• Hosted login — the sign-in page and the redirect_url round trip.
• .NET EndUser auth — using this client from Blazor WebAssembly.
• SDK overview — which package to use where.