---
title: "sdk/go"
description: "SDK de servidor Go para verificação JWT sem rede, autenticação derequisições e validação de assinatura de webhook."
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.

# sdk/go

## 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 XID ativa) ainda não foi realizada e deve serconcluída antes do uso em produção.

## Instalar

```shell
go get github.com/StringKe/xid/sdk/go
```

## Início rápido

Crie um `Client` na inicialização do aplicativo e reutilize-oentre requisições. O cliente faz cache do JWKS internamente com TTLconfigurável.

```go
import "github.com/StringKe/xid/sdk/go/xid"

client, err := xid.NewClient(xid.ClientOptions{
Issuer:        "https://xid.dev",
Audience:      "your-client-id",
WebhookSecret: "whs_...",
})
if err != nil {
log.Fatal(err)
}

// HTTP middleware (recommended)
http.Handle("/api/", client.Middleware(apiHandler, func(w http.ResponseWriter, r *http.Request) {
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
}))

// Inside a protected handler
func apiHandler(w http.ResponseWriter, r *http.Request) {
claims := xid.ClaimsFromContext(r.Context())
fmt.Fprintf(w, "hello %s", claims.Subject)
}
```

## Verifica o token diretamente

```go
claims, err := client.VerifyAccessToken(ctx, tokenString)
if err != nil {
// handle verification failure
}
fmt.Println(claims.Subject, claims.OrgID)
```

## Verifica webhook

```go
func webhookHandler(w http.ResponseWriter, r *http.Request) {
event, err := client.VerifyWebhook(r)
if err != nil {
    http.Error(w, "invalid signature", http.StatusBadRequest)
    return
}
// event.Body: raw JSON body
// event.ID:   svix-id for idempotency
w.WriteHeader(http.StatusNoContent)
}
```

## API principal

| Símbolo | Descrição |
| --- | --- |
| `NewClient(opts)` | Constrói o cliente. `Issuer` é obrigatório; os demais campos sãoopcionais. |
| `(*Client).VerifyAccessToken(ctx, token)` | Verifica uma string JWT, retorna `*Claims` ou erro. |
| `(*Client).AuthenticateRequest(ctx, r)` | Extrai e verifica o token de uma requisição HTTP. Sempre retorna`AuthState`, não entra em pânico. |
| `(*Client).Middleware(next, onUnauthorized)` | Middleware padrão `net/http`. Injeta `*Claims` no contextoem caso de sucesso. |
| `ClaimsFromContext(ctx)` | Extrai claims injetados pelo Middleware. |
| `(*Client).VerifyWebhook(r)` | Verifica a assinatura da requisição de webhook. Retorna`*WebhookEvent` com o body bruto em caso de sucesso. |

## ClientOptions

| Campo | Padrão | Descrição |
| --- | --- | --- |
| `Issuer` | obrigatório | URL do emissor XID |
| `Audience` | vazio (ignorar) | Claim JWT aud esperado |
| `WebhookSecret` | vazio | Segredo de assinatura HMAC do webhook |
| `JWKSCacheTTL` | `1h` | TTL do cache local do JWKS |
| `HTTPClient` | Timeout padrão de 10s | Cliente HTTP para busca de JWKS |

## Notas da plataforma

- ES256 é o algoritmo principal; RS256 é suportado paracompatibilidade. ES384 e ES512 ainda não estão implementados.
- O JWKS é buscado de `{issuer}/jwks`. A detecção automática deOIDC Discovery é uma melhoria planejada.
- `Claims` incorpora `jwt.RegisteredClaims` e adiciona`ClientID`, `Scope`, `AMR`, `ACR`, `OrgID`,`OrgSlug`.

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