---
title: "Go net/http Adapter"
url: "https://docs.caracal.run/v1.0/sdks/adapters/nethttp/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/sdks/adapters/nethttp.md"
description: "Go middleware for protecting HTTP handlers with Caracal mandate verification."
page_type: "page"
concepts: []
requires: []
---

# Go net/http Adapter

Canonical URL: https://docs.caracal.run/v1.0/sdks/adapters/nethttp/
Markdown URL: https://docs.caracal.run/markdown/v1.0/sdks/adapters/nethttp.md
Description: Go middleware for protecting HTTP handlers with Caracal mandate verification.
Page type: page
Concepts: none
Requires: none

---

The Go net/http adapter wraps handlers with verify-engine verification and stores verified claims in the request context.

Use it for inbound `net/http` handlers. It does not create outbound Caracal context or replace the Go application SDK.

## Install

```bash
go get github.com/garudex-labs/caracal/packages/adapters/nethttp/go
```

## Middleware

```go
import (
	"net/http"
	"time"

	nethttp "github.com/garudex-labs/caracal/packages/adapters/nethttp/go"
	revocation "github.com/garudex-labs/caracal/packages/revocation/go"
	verify "github.com/garudex-labs/caracal/packages/verify/go"
)

revocations := revocation.NewInMemoryStore(24 * time.Hour)

verifier := verify.NewVerifier(verify.Options{
	Issuer:          "https://sts.pipernet.example",
	Audience:        "https://api.pipernet.example",
	ZoneID:          "0195f2a9-1b22-7c3d-9e4f-5a6b7c8d9e0f",
	Revocations:     revocations,
})

handler := nethttp.VerifierMiddleware(verifier.Require(verify.Options{
	RequiredScopes:  []string{"pipernet:read"},
	RequiredTargets: []string{"resource://pipernet"},
	RequireSession:  true,
}))(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	claims, ok := nethttp.ClaimsFromContext(r.Context())
	if !ok {
		http.Error(w, "missing claims", http.StatusUnauthorized)
		return
	}
	_, _ = w.Write([]byte(claims.Sub))
}))
```

## APIs

| API | Purpose |
| --- | --- |
| `Middleware(opts)` | Return middleware that verifies the bearer token and rejects failed requests. |
| `VerifierMiddleware(verifier)` | Return middleware backed by a reusable verifier with shared defaults. |
| `ClaimsFromContext(ctx)` | Retrieve verified Caracal claims inside a handler. |

`Middleware` constructs a verifier from `verify.Options`; `VerifierMiddleware` reuses an existing verifier. A nil verifier produces a verifier with empty options and therefore cannot establish a properly configured production boundary; always pass trusted issuer, audience, zone, and revocation settings.

## Failure behavior

The middleware maps verification errors to HTTP failures before the handler runs and includes a safe `error_hint` in JSON failures. Use a shared revocation store through `verify.Options` in production so revoked sessions are rejected consistently across service instances.

## Related Pages

* [Protect a Go net/http Service](/v1.0/guides/protect-nethttp/)
* [Go SDK](/v1.0/sdks/go/)
* [Verify Package](/v1.0/sdks/verify/)