---
title: Go-Server-SDK
---

# Go-Server-SDK

Offizielles serverseitiges Go-SDK — `github.com/Captcha-La/captchala-go`.

Drei Aufgaben, die das SDK für Sie übernimmt:

1. **Validate** — verifiziert einen `pt_`-Pass-Token aus dem Browser-SDK.
2. **Issue** — stellt einen Einmal-`sct_`-Server-Token aus, um die anstehende Challenge an eine bestimmte action / IP / UID zu binden.
3. **Moderate** — multimodale (Text + Bild) Content-Moderation gegen dieselbe OpenAI-kompatible Pipeline, die auch das Dashboard verwendet.

## Installation

```bash
go get github.com/Captcha-La/captchala-go
```

Ausschließlich Standardbibliothek. Keine externen Abhängigkeiten.

## Validate (`pt_`-Token)

Übergeben Sie die IP des Endnutzers (aus `CF-Connecting-IP` / `X-Forwarded-For`,
mit Rückfall auf `RemoteAddr`). Optional, aber **empfohlen** — sie wird für
zusätzliche Risikoprüfungen verwendet.

```go
import captchala "github.com/Captcha-La/captchala-go"

client := captchala.NewClient(appKey, appSecret)

func handler(w http.ResponseWriter, r *http.Request) {
    token := r.FormValue("captcha_token")

    result, err := client.ValidateWithClientIP(token, false, clientIP(r))
    if err != nil || !result.Valid {
        http.Error(w, result.Error, http.StatusBadRequest)
        return
    }
    // Verification passed; proceed with the request.
    // result.CaptchaArgs has Platform / UserIP / Referer / Pkg / SolvedAt / RiskScore
}

// Real end-user IP behind a CDN / proxy
func clientIP(r *http.Request) string {
    if ip := r.Header.Get("CF-Connecting-IP"); ip != "" {
        return ip
    }
    if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
        return strings.TrimSpace(strings.Split(xff, ",")[0])
    }
    host, _, _ := net.SplitHostPort(r.RemoteAddr)
    return host
}
```

Keine IP zur Hand? Verwenden Sie `client.Validate(token)` — die Verifizierung
funktioniert weiterhin, nur ohne das zusätzliche IP-basierte Risikosignal.

Falls der ursprüngliche `server_token` mit `bind_uid` ausgestellt wurde, vergleichen Sie:

```go
if result.UID != expectedUserID {
    http.Error(w, "user mismatch", http.StatusBadRequest)
    return
}
```

Der Kontext zum Lösungszeitpunkt wird zudem in `result.CaptchaArgs` zu Ihrer
Referenz zurückgegeben:

```go
ip := result.CaptchaArgs.UserIP   // zum Lösungszeitpunkt erfasste Besucher-IP
```

## Server-Token ausstellen

Empfohlen für hochwertige Flows (Anmeldung, Registrierung, Bezahlung): Das Backend stellt einen
Einmal-`sct_`-Token aus, übergibt ihn an den Browser, der Browser verwendet ihn als
`serverToken`-Prop. Einmal-, action-bezogen, optional IP/UID-gebunden.

```go
issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // backend rejects token if a different IP redeems it
    TTL:       300,       // seconds
    MaxUses:   5,         // SDK retry budget
    BindUID:   userID,    // pair with ValidateResult.UID on verify
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// hand issue.Token to the browser
```

Abkürzung nur mit Standardwerten:

```go
issue, err := client.IssueServerToken("login")
```

## Inhalte moderieren

Multimodal — akzeptiert einen Slice von `ModerationItem` (Text und/oder image_url im
OpenAI-kompatiblen Format):

```go
result, err := client.ModerationCheck([]captchala.ModerationItem{
    captchala.TextItem(userComment),
    captchala.ImageURLItem(uploadedImageURL),
}, userID)

if err != nil || !result.OK {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}

if result.Flagged {
    if result.HasCategory("violence", "csam") {
        // hard block
    }
}
```

Reine-Text-Abkürzung:

```go
result, err := client.ModerationText("user comment here", userID)
```

Kategorien werden vom Modell definiert; iterieren Sie `result.Categories` defensiv, statt
einen festen Satz hart zu kodieren.

## Typen

| Typ | Felder |
|---|---|
| `ValidateResult` | `Valid`, `Error`, `UID`, `ChallengeID`, `Action`, `Offline`, `ClientOnly`, `Warning`, `CaptchaArgs` |
| `CaptchaArgs` | `Platform`, `UserIP`, `Referer`, `Pkg`, `SolvedAt`, `RiskScore` (rein informativ) |
| `IssueResult` | `OK`, `Token`, `ExpiresIn`, `IssuedAt`, `Error`, `Message` |
| `IssueOptions` | `BindingIP`, `TTL`, `MaxUses`, `BindUID` |
| `ModerationItem` | `Type`, `Text`, `ImageURL` (Helper `TextItem()` / `ImageURLItem()` verwenden) |
| `ModerationResult` | `OK`, `Flagged`, `Categories`, `ContentType`, `Raw`, `Error`, `Message`; Methode `HasCategory(...names)` |

## Links

- [pkg.go.dev](https://pkg.go.dev/github.com/Captcha-La/captchala-go) · [GitHub](https://github.com/Captcha-La/captchala-go)
- [Web-SDK-Übersicht](/de/web-sdk) · [API-Referenz](/de/api-reference)