---
title: "@xid-kit/core"
description: "Cliente do navegador para estado de sessão, acesso JWT de curta duração e auxiliares da Management API."
locale: "pt-BR"
---

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

# @xid-kit/core

## Instalar e configurar

Aponte `apiUrl` para a origem da sua instância XID (hospedada ou auto-hospedada). O SDK nunca armazena segredo do cliente nem expõe material de refresh token a scripts do navegador.

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

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

## Ciclo de vida da sessão

- `load()` lê `/v1/me` e popula o usuário, a sessão e a organização ativa.
- `signInPassword()` estabelece uma sessão via cookie pelo fluxo de senha do Hosted Auth.
- `getToken()` retorna um JWT de curta duração para chamadas de API. Verifique sem rede no seu servidor com JWKS.
- `setActiveOrganization()` alterna o contexto da organização e limpa o cache de token antes de recarregar o estado.
- `signOut()` revoga o cookie de sessão do navegador.

## Auxiliares da Management API

A versão atual encapsula apenas o gerenciamento de chaves de API. Todos os outros recursos da Management API exigem chamadas REST diretas a `/v1/` com `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)
```

## API exportada

| Exportar | Tipo | Finalidade |
| --- | --- | --- |
| `XidClient` | class | Cliente de navegador de nível superior: load, signIn, getToken, setActiveOrganization, signOut e auxiliares da Management API |
| `XidStore` | class | Store reativo independente de framework; assine com useSyncExternalStore nos bindings de framework |
| `TokenManager` | class | Cache de JWT de curta duração e renovação agendada (uso avançado e testes) |
| `XidApiClient` | class | Cliente HTTP para os endpoints /v1/me e de token |
| `XidNetworkError` | class | Lançado em falhas de transporte: erro de rede, resposta não JSON, 5xx sem corpo estruturado |
| `makeXidError` | function | Constrói um XidError estruturado para falhas de validação locais sem chamada de rede |
| `isXidErrorShape` | function | Type guard: verifica se um valor desconhecido está em conformidade com o formato XidError recebido na rede |
| `decodeTokenClaims` | function | Decodifica as declarações do payload JWT apenas para agendamento de expiração; não verifica a assinatura |
| `isTokenExpiring` | function | Retorna true quando o token expira dentro da janela de tolerância (padrão 10 s) |
| `SESSION_STATUS` | tupla as const | Valores válidos de status de sessão: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | tupla as const | Valores válidos de status do cliente: loading, ready, degraded, error |
| `PACKAGE` | constante de string | Identificador de nome de pacote '@xid-kit/core' |

## Tipos

| Tipo | Descrição |
| --- | --- |
| `XidUser` | Visão somente leitura do usuário autenticado (sem segredos ou hashes) |
| `XidOrganization` | Visão pública da organização |
| `XidOrganizationMembership` | Associação do usuário em uma organização com papel e permissões |
| `XidSession` | Visão da sessão incluindo status, expiração e organização ativa |
| `XidApiKey` | Chave de API sem segredo (visualização em lista) |
| `XidApiKeyWithSecret` | Chave de API retornada uma única vez na criação; inclui o campo key |
| `XidPage<T>` | Envelope de resposta paginado por cursor |
| `CreateApiKeyInput` | Entrada para createApiKey |
| `SignInPasswordInput` | Entrada para signInPassword |
| `SignInResult` | Resultado de signInPassword: próximo passo ou URL de redirecionamento |
| `SessionStatus` | União dos valores de SESSION\_STATUS |
| `ClientStatus` | União dos valores de CLIENT\_STATUS |
| `XidState` | Snapshot completo do estado do SDK obtido por assinatura do XidStore |
| `XidStateListener` | Tipo de callback para listener de mudança de estado |
| `Unsubscribe` | Tipo de retorno de XidStore.subscribe |
| `GetTokenOptions` | Opções para getToken: template, skipCache, leewaySeconds, signal |
| `XidClientOptions` | Opções do construtor de XidClient: apiUrl, fetcher, now |
| `TokenResponse` | Formato bruto da resposta do endpoint de token |
| `ClientStateResponse` | Formato bruto da resposta de /v1/me |
| `DecodedTokenClaims` | Declarações do payload JWT retornadas por decodeTokenClaims |

## Documentação relacionada

Bindings de framework: [@xid-kit/react](/pt-br/sdks/react). Verificação no servidor: [@xid-kit/backend](/pt-br/sdks/backend).

Source: https://xid.dev/pt-br/sdks/core/index.mdx