SDK overview

Axowl ships four SDK families. Web front-ends use the JS/TS one; on the server pick the client for your runtime — .NET, Node, Python or Java. Every backend SDK does the same three things the same way: verify the end-user token against your org’s JWKS, read permissions with the same wildcard rules, and (optionally) ask Axowl for a server-authoritative answer.

Runtime	Package	Registry	Page
Browser / React 18 or 19	`@axowl/sdk`	npm	Quickstart
Node / Next.js	`@axowl/sdk-backend`	npm	below
.NET 10	`Axowl.Sdk.Identity.Client` (+ Integrity, Eventing, Korean Identity)	nuget.org	Identity
Python 3.9+	`axowl-sdk`	PyPI	Python
Java 17+	`com.axowl:axowl-sdk`	Maven Central	Java

Every package name, registry link and install command is on SDK packages.

JavaScript / TypeScript

Package	Purpose
`@axowl/sdk`	React provider, hooks & components — `AxowlProvider`, `useAxowl`, `usePermission`, `useSession`, `useOrg`, plus drop-in `SignIn`, `SignInButton`, `UserButton`
`@axowl/sdk-backend`	Express middleware (`axowlMiddleware`, `requirePermission`) and Next.js helpers (`getAuthAsync`, `canAccess`); JWT verification against the org JWKS (`verifyTokenAsync`)
`@axowl/sdk-analytics`	Behavior analytics — page views, time on page, sessions, opt-in clicks, named events; also a one-script-tag `beacon.js`. · guide
`@axowl/sdk-core`	Framework-free client, token store and permission matching — `@axowl/sdk` is built on it; use it directly outside React · reference

import { AxowlProvider, useAxowl, usePermission } from '@axowl/sdk';

<AxowlProvider orgSlug="my-org" clientId="client_..." baseUrl="https://api.axowl.com"><App /></AxowlProvider>

const { user, isSignedIn, signIn } = useAxowl();
const { can } = usePermission();           // can('dashboard.view')

clientId is the application’s client key (client_..., one per platform × environment, from Applications in the dashboard). The client talks to /api/public/apps/{clientId}/... — login methods, magic link, social, federated, passkey, session handshake.

Features: magic link, social, passkey (FIDO2), and federated (OIDC) sign-in; JWT auto-refresh; wildcard permission matching (sap.fi.*); Express req.axowl context; Next.js App Router & Middleware support; TypeScript-first.

Selling plans to your members (app member purchases)

Your app’s signed-in members buy the plans of your app group; they pay on Stripe Checkout or on the Axowl payment page (your own PortOne / Razorpay), and the purchase appears once the payment is confirmed.

Call the member-purchase endpoints from your app:

Endpoint	Auth	What it does
`GET /api/public/apps/{clientId}/plans`	none	The plans a member can buy in this app.
`POST /api/public/apps/{clientId}/checkout`	member’s access token	Starts a purchase (`productKey`, `billingCycle`, `returnUrl`). Answers a Stripe `redirectUrl`, or a `payUrl` on the Axowl payment page.
`GET /api/public/apps/{clientId}/me/entitlements`	member’s access token	What the member has bought; `active` is `true` while they may use it.
`POST /api/public/apps/{clientId}/me/subscriptions/{orderId}/cancel`	member’s access token	Cancels a subscription at the end of the paid period.

returnUrl must be on an origin registered on the application. Your server can forward the member’s token to me/entitlements to get the same answer. Request and response fields: Applications → App member purchases.

.NET (`Axowl.Sdk.*`)

Package	Purpose	Page
`Axowl.Sdk.Identity.Client`	Introspection, permission checks, `[RequirePermission]`	Identity
`Axowl.Sdk.Integrity.Client`	Seal records and verify them	Integrity
`Axowl.Sdk.Eventing.Client`	Publish custom events / poll sealed events	Eventing
`Axowl.Sdk.Korean.Identity.Client`	`[RequireKoreanIdentity]` gating	Korean Identity

The packages target .NET 10 (net10.0). Each client has the same Transport option: TransportMode.Grpc (the default — gRPC to https://grpc.axowl.com), TransportMode.GrpcWithFallback (gRPC first, REST when gRPC cannot get through) and TransportMode.RestOnly (REST to https://api.axowl.com). Blazor end-user sign-in uses hosted login with @axowl/sdk-core — see .NET EndUser auth.

Python

pip install axowl-sdk. verify_token (RS256 against the org JWKS, issuer/audience/expiry), AxowlContext with typed claims and a decoded permission list, axowl.fastapi.AxowlAuth (dependency + require("scope")), and AxowlIdentityClient for introspect / check-permission. See Python SDK.

Java

com.axowl:axowl-sdk. AxowlTokenVerifier (RS256 against the org JWKS, cached and rate-limited), AxowlContext record, Permissions (wildcard matching + require), AxowlAuthFilter for servlet containers such as Spring Boot, and AxowlIdentityClient for introspect / check-permission. See Java SDK.

Timeouts and caching

Every client gives up instead of waiting forever on a stalled connection.

SDK	Setting	Default	Notes
JavaScript (`@axowl/sdk-core`)	`requestTimeoutMs`	15000	Applies to every request the client makes. `0` turns it off.
.NET (`Axowl.Sdk.Identity.Client`, `.Integrity.Client`, `.Eventing.Client`, `.Korean.Identity.Client`)	`CallTimeout`	10 seconds	gRPC deadline and REST timeout for each call.

Other behavior worth knowing:

JavaScript: the list of sign-in methods is cached per client for 5 minutes, and concurrent calls share one request. A change made in the dashboard shows up within that time. A failed fetch is not cached.
.NET: the signing-key set (JWKS) is refreshed every hour, so a rotated key is picked up within the hour. The event polling service waits PollInterval (default 5 seconds, with ±20% jitter) when there is nothing new, and backs off exponentially after a failed poll.

The token every backend SDK verifies

An Axowl end-user access token is an RS256 JWT with iss = {api}/api/public/orgs/{orgSlug}, aud = your application's client key, sub = end-user id, and the claims email, org, org_slug, app, app_group, type ("enduser"), is_employee, cid (the user’s org badge) and permissions (a JSON-encoded string array). Keys are published per organization at {api}/api/public/orgs/{orgSlug}/.well-known/jwks.json. All four backend SDKs verify against exactly that, so a token accepted by one is accepted by the others.