Authdog's Go module resolves sessions for Go web services. **Gin is the only framework with a ready-made adapter.** `net/http`, chi, Echo, and other routers require manual integration with core functions.

## Availability and install

```bash
go get github.com/authdog/web-sdk/packages/go@latest
```

```go
import authdog "github.com/authdog/web-sdk/packages/go"
```

The module is public source, has no tagged module versions, and currently resolves as an untagged pseudo-version. Pin a commit for reproducible builds. It declares Go 1.25 and directly depends on Gin 1.10.

## Configure

Create one client with your environment's public key (`pk_...`):

```go
ad, err := authdog.New(authdog.Config{
    PublicKey: os.Getenv("PK_AUTHDOG"),
})
if err != nil {
    log.Fatal(err)
}
```

The key is safe to expose. `New` rejects malformed keys and identity hosts outside the trusted HTTPS allowlist. `Config.HTTPClient` can provide timeout, transport, and observability policy.

## Attach and protect (Gin)

Mount `AttachSession()` before routes and `RequireAuth()` on protected routes:

```go
r := gin.Default()
r.Use(ad.AttachSession())

r.GET("/me", ad.RequireAuth(), func(c *gin.Context) {
    c.JSON(http.StatusOK, authdog.FromGin(c).User)
})

r.GET("/logout", ad.Logout)
r.Run(":3000")
```

`AttachSession` prefers the `authdog-session` cookie, then reads `Authorization: Bearer <token>`. It calls the environment's OIDC `userinfo` endpoint and stores:

```go
type Context struct {
    Token           string
    User            any
    IsAuthenticated bool
    UserInfo        *UserInfoResponse
}
```

Missing, invalid, or unverifiable tokens yield anonymous context and do not abort. Only `meta.code == 200` with a user sets `IsAuthenticated`. `RequireAuth` is the authentication boundary and returns `401 {"error":"Unauthorized"}` otherwise.

To disable `userinfo`:

```go
fetchUser := false
ad, err := authdog.New(authdog.Config{
    PublicKey: os.Getenv("PK_AUTHDOG"),
    FetchUser: &fetchUser,
})
```

With `FetchUser` disabled, only `Context.Token` is populated; `User` remains nil and `IsAuthenticated` remains false. Built-in `RequireAuth` therefore rejects every such token. Use this mode only when separate server-side validation and enforcement replace Authdog's gate.

## Other routers

No `net/http`, chi, or Echo middleware is shipped. Manual adapters can compose `ValidateAndParsePublicKey`, `GetSessionToken`, `FetchUserData`, `IsAuthenticatedUserInfo`, and `SanitizeRedirectPath`. Your adapter must propagate request cancellation, treat lookup failures as unauthenticated, and enforce authentication before protected handlers.

## Security boundaries

- `AttachSession` is informational; `RequireAuth` is the Gin security boundary.
- Authentication does not grant application permissions. Apply [authorization](/docs/concepts/authorization) separately.
- Bearer tokens are sent only to a trusted HTTPS identity host. Self-hosted hosts require explicit `AUTHDOG_ALLOWED_IDENTITY_HOSTS` entries.
- `Logout` clears the local cookie and sanitizes `redirect_uri`; it does not revoke bearer tokens or end an upstream provider session.

## Next steps

- [Backend requests](/docs/backend)
- [Calling the REST API](/docs/api)