---
title: "@xid-kit/core"
description: "세션 상태, 단기 JWT 접근, 관리 API 헬퍼를 위한 브라우저 클라이언트입니다."
locale: "ko"
---

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

# @xid-kit/core

## 설치 및 설정

`apiUrl`을 XID 인스턴스 origin (호스팅 또는 셀프 호스팅)으로 지정하세요. SDK는 클라이언트 비밀값을 저장하지 않으며 refresh token 자료를 브라우저 스크립트에 노출하지 않습니다.

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

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

## 세션 수명주기

- `load()`은 `/v1/me`를 읽어 사용자, 세션, 활성 조직을 초기화합니다.
- `signInPassword()`는 Hosted Auth 비밀번호 흐름을 통해 cookie 세션을 생성합니다.
- `getToken()`은 API 호출용 단기 JWT를 반환합니다. 백엔드에서 JWKS를 이용해 네트워크 호출 없이 검증하세요.
- `setActiveOrganization()`은 조직 컨텍스트를 전환하고 상태를 다시 로드하기 전에 token 캐시를 초기화합니다.
- `signOut()`은 브라우저 세션 cookie를 폐기합니다.

## 관리 API 헬퍼

현재 버전은 API 키 관리만 래핑합니다. 다른 모든 관리 API 리소스는 `Authorization: Bearer sk_live_xxx`를 사용한 직접 `/v1/` REST 호출이 필요합니다.

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

## 내보내진 API

| 내보내기 | 종류 | 목적 |
| --- | --- | --- |
| `XidClient` | class | 최상위 브라우저 클라이언트: load, signIn, getToken, setActiveOrganization, signOut 및 관리 API 헬퍼 |
| `XidStore` | class | 프레임워크에 독립적인 반응형 store; 프레임워크 바인딩에서 useSyncExternalStore로 구독합니다 |
| `TokenManager` | class | 단기 JWT 캐시 및 예약 갱신 (고급 사용 및 테스트) |
| `XidApiClient` | class | /v1/me 및 token 엔드포인트용 HTTP 클라이언트 |
| `XidNetworkError` | class | 전송 실패 시 던집니다: 네트워크 오류, JSON이 아닌 응답, 구조화된 본문이 없는 5xx |
| `makeXidError` | function | 네트워크 왕복 없이 로컬 검증 실패에 대한 구조화된 XidError를 생성합니다 |
| `isXidErrorShape` | function | 타입 가드: 알 수 없는 값이 네트워크의 XidError 형태를 따르는지 확인합니다 |
| `decodeTokenClaims` | function | 만료 스케줄링 전용으로 JWT 페이로드 클레임을 디코딩합니다; 서명은 검증하지 않습니다 |
| `isTokenExpiring` | function | 토큰이 leeway 창 내에서 만료될 때 true를 반환합니다 (기본값 10초) |
| `SESSION_STATUS` | as const 튜플 | 유효한 세션 상태 값: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | as const 튜플 | 유효한 클라이언트 상태 값: loading, ready, degraded, error |
| `PACKAGE` | 문자열 상수 | 패키지 이름 식별자 '@xid-kit/core' |

## 타입

| 유형 | 설명 |
| --- | --- |
| `XidUser` | 인증된 사용자의 읽기 전용 보기 (비밀값 및 해시 제외) |
| `XidOrganization` | 공개 조직 보기 |
| `XidOrganizationMembership` | 역할 및 권한이 포함된 조직 내 사용자 멤버십 |
| `XidSession` | 상태, 만료, 활성 조직을 포함한 세션 보기 |
| `XidApiKey` | 비밀값이 없는 API 키 (목록 보기) |
| `XidApiKeyWithSecret` | 생성 시 한 번만 반환되는 API 키; key 필드 포함 |
| `XidPage<T>` | cursor 기반 페이지네이션 응답 envelope |
| `CreateApiKeyInput` | createApiKey 입력 |
| `SignInPasswordInput` | signInPassword 입력 |
| `SignInResult` | signInPassword 결과: 다음 단계 또는 리디렉션 URL |
| `SessionStatus` | SESSION\_STATUS 값의 union |
| `ClientStatus` | CLIENT\_STATUS 값의 union |
| `XidState` | XidStore에서 구독하는 전체 SDK 상태 스냅샷 |
| `XidStateListener` | 상태 변경 리스너 callback 타입 |
| `Unsubscribe` | XidStore.subscribe의 반환 타입 |
| `GetTokenOptions` | getToken 옵션: template, skipCache, leewaySeconds, signal |
| `XidClientOptions` | XidClient 생성자 옵션: apiUrl, fetcher, now |
| `TokenResponse` | token 엔드포인트 응답 원본 형태 |
| `ClientStateResponse` | /v1/me 응답 원본 형태 |
| `DecodedTokenClaims` | decodeTokenClaims가 반환하는 JWT 페이로드 클레임 |

## 관련 문서

프레임워크 바인딩: [@xid-kit/react](/ko/sdks/react). 서버 검증: [@xid-kit/backend](/ko/sdks/backend).

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