---
title: "@xid-kit/core"
description: "Browser client for session state, short-lived JWT access, and Management API helpers."
locale: "en"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/en/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/core

## 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.

```ts
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`.

```ts
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 |

## Related docs

Framework bindings: [@xid-kit/react](/sdks/react). Server verification: [@xid-kit/backend](/sdks/backend).

Source: https://xid.dev/sdks/core/index.mdx