@xid-kit/core

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

Install and configure

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

For a developer app on another origin, configure mode: 'oidc' with issuer, clientId, and an exact redirectUri. Use same-origin mode only when the application routes Core auth endpoints on its exact origin. XID has no publishable-key credential.

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

const xid = new XidClient({
  mode: 'oidc',
  issuer: 'https://xid.dev',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await xid.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)

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

Management API helpers are server-side or exact same-origin only. Construct a separate client with sk_live_* or sk_test_* on the server; OIDC browser mode rejects these operations.

const management = new XidClient({
  apiUrl: 'https://xid.dev',
  secretKey: process.env.XID_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)

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: skipCache, leewaySeconds, signal
`XidClientOptions`	Discriminated XidClient constructor options: same-origin accepts apiUrl, secretKey, fetcher, and now; oidc requires issuer, clientId, and redirectUri.
`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.