@xid-kit/core

Browser client for session state, short-lived JWT access, and Management API helpers.

Install and configure

Point apiUrl at your XID instance origin (hosted or self-hosted). The SDK never stores a client secret and does not expose refresh token material to browser scripts.

import { XidClient } from '@xid-kit/core'

const xid = new XidClient({ apiUrl: 'https://xid.dev' })
await xid.load()
const token = await xid.getToken()

Session lifecycle

load() reads /v1/me and hydrates user, session, and active organization.
signInPassword() establishes a cookie session through Hosted Auth password flow.
getToken() returns a short-lived JWT for API calls. Verify networklessly on your backend with JWKS.
setActiveOrganization() switches org context and clears the token cache before reloading state.
signOut() revokes the browser session cookie.

Management API helpers

The current version wraps API key management only. All other Management API resources require direct /v1/ REST calls with Authorization: Bearer sk_live_xxx.

const keys = await xid.listApiKeys()
const created = await xid.createApiKey({ name: 'CI deploy', scopes: ['read'] })
await xid.revokeApiKey(created.id)

Exported API

Export	Kind	Purpose
`XidClient`	class	Top-level browser client: load, signIn, getToken, setActiveOrganization, signOut, and Management API helpers
`XidStore`	class	Framework-agnostic reactive store; subscribe with useSyncExternalStore in framework bindings
`TokenManager`	class	Short-lived JWT cache and scheduled refresh (advanced use and testing)
`XidApiClient`	class	HTTP client for /v1/me and token endpoints
`XidNetworkError`	class	Thrown on transport failures: network error, non-JSON response, 5xx with no structured body
`makeXidError`	function	Construct a structured XidError for local validation failures without a network round-trip
`isXidErrorShape`	function	Type guard: checks whether an unknown value conforms to XidError shape from the wire
`decodeTokenClaims`	function	Decode JWT payload claims for expiry scheduling only; does not verify the signature
`isTokenExpiring`	function	Returns true when the token expires within the leeway window (default 10 s)
`SESSION_STATUS`	as const tuple	Valid session status values: active, pending, expired, removed, ended, revoked
`CLIENT_STATUS`	as const tuple	Valid client status values: loading, ready, degraded, error
`PACKAGE`	string constant	Package name identifier ‘@xid-kit/core’

Types

Type	Description
`XidUser`	Read-only view of the authenticated user (no secrets or hashes)
`XidOrganization`	Public organization view
`XidOrganizationMembership`	User membership in an org with role and permissions
`XidSession`	Session view including status, expiry, and active org
`XidApiKey`	API key without secret (list view)
`XidApiKeyWithSecret`	API key returned once at creation; includes the key field
`XidPage<T>`	Cursor-paginated response envelope
`CreateApiKeyInput`	Input for createApiKey
`SignInPasswordInput`	Input for signInPassword
`SignInResult`	Result from signInPassword: next step or redirect URL
`SessionStatus`	Union of SESSION_STATUS values
`ClientStatus`	Union of CLIENT_STATUS values
`XidState`	Full SDK state snapshot subscribed from XidStore
`XidStateListener`	State change listener callback type
`Unsubscribe`	Return type of XidStore.subscribe
`GetTokenOptions`	Options for getToken: template, skipCache, leewaySeconds, signal
`XidClientOptions`	Constructor options for XidClient: apiUrl, fetcher, now
`TokenResponse`	Raw token endpoint response shape
`ClientStateResponse`	Raw /v1/me response shape
`DecodedTokenClaims`	JWT payload claims returned by decodeTokenClaims

Framework bindings: @xid-kit/react. Server verification: @xid-kit/backend.