---
title: "sdk/java"
description: "SDK de servidor Java 17+ para verificação JWT sem rede, autenticaçãode requisições HTTP e validação de assinatura de webhook."
locale: "pt-BR"
---

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

# sdk/java

## Estado

Implementado e verificado localmente. A verificação de ida e voltacom um IdP real (busca de JWKS, assinatura/verificação de tokencontra uma instância Vonvon ativa) ainda não foi realizada e deve serconcluída antes do uso em produção.

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

A autenticação de requisições aceita somente Bearer por padrão. Um cookie JWT pertencente ao aplicativo só é lido quando seu nome exato é configurado. O cookie opaco do Core \_\_Host-vonvon.rt.\* nunca é pesquisado nem verificado localmente; troque-o encaminhando o header Cookie completo para o POST /v1/sessions/token da mesma origem exata, com redirects desativados, e aceite somente uma resposta que contenha apenas o campo token.

## Instalar

Java 17+ e Maven obrigatórios.

```xml
<!-- First install the source checkout: cd sdk/java && mvn install -->
<dependency>
  <groupId>dev.vonvon</groupId>
  <artifactId>vonvon-sdk-java</artifactId>
  <version>0.1.0-alpha.0</version>
</dependency>
```

## Início rápido

Construa um `VonvonClient` na inicialização do aplicativo e use-ocomo singleton.

```java
import dev.vonvon.sdk.VonvonClient;
import dev.vonvon.sdk.VonvonClientOptions;
import dev.vonvon.sdk.VonvonClaims;
import dev.vonvon.sdk.VonvonTokenException;
import dev.vonvon.sdk.VonvonJwksException;

VonvonClient vonvon = VonvonClient.create(
VonvonClientOptions.builder()
    .issuer("https://vonvon.id")
    .audience("your-client-id")
    .webhookSecret("whsec_xxx")
    .build()
);

try {
VonvonClaims claims = vonvon.verifyToken(accessToken);
String userId = claims.getSub();
String scope  = claims.getScope();
} catch (VonvonTokenException e) {
response.sendError(401, "Unauthorized: " + e.getReason());
} catch (VonvonJwksException e) {
response.sendError(503, "Service unavailable");
}
```

## Autentica uma requisição HTTP

```java
import dev.vonvon.sdk.AuthResult;

// Bearer-only by default
AuthResult result = vonvon.authenticateRequest(request.getHeader("Authorization"), null);

if (result.isAuthenticated()) {
String userId = result.getClaims().get().getSub();
} else {
response.sendError(401);
}

String token = vonvon.exchangeSessionToken(
request.getRequestURL().toString(),
request.getHeader("Cookie"),
"/v1/sessions/token"
);
```

## Verifica webhook

```java
import dev.vonvon.sdk.VonvonWebhookException;

byte[] rawBody = request.getInputStream().readAllBytes();
Map<String, String> headers = Map.of(
"svix-id",        request.getHeader("svix-id"),
"svix-timestamp", request.getHeader("svix-timestamp"),
"svix-signature", request.getHeader("svix-signature")
);

try {
vonvon.verifyWebhook(headers, rawBody);
} catch (VonvonWebhookException e) {
response.sendError(400, "Invalid webhook: " + e.getReason());
}
```

## VonvonClientOptions

| Método | Padrão | Descrição |
| --- | --- | --- |
| `.issuer(String)` | obrigatório | Emissor OIDC; deve corresponder exatamente ao iss do token |
| `.audience(String)` | `null` | aud esperado; null ignora a validação |
| `.webhookSecret(String)` | `null` | Segredo do webhook (prefixo `whsec_` ou base64 puro) |
| `.jwksCacheDuration(Duration)` | 1 hora | TTL do cache em memória do JWKS |
| `.clockSkewTolerance(Duration)` | 30 segundos | Tolerância de desvio de relógio para exp/nbf |
| `.connectTimeout(Duration)` | 5 segundos | Timeout de conexão HTTP para busca de JWKS |
| `.readTimeout(Duration)` | 10 segundos | Timeout de leitura HTTP para busca de JWKS |

## Notas da plataforma

- Usa `nimbus-jose-jwt` para parsing de JWT/JWKS. ES256 éprimário; RS256 e PS256 são suportados.
- Todas as APIs públicas são síncronas e thread-safe.
- Logging via fachada SLF4J; traga sua própria implementação (Logback,Log4j2).
- Hierarquia de exceções: `VonvonException` -&gt;`VonvonTokenException`, `VonvonJwksException`,`VonvonWebhookException`.

Source: https://vonvon.id/pt-br/sdks/java/index.mdx