VVEREID Docs
Search docsGitHub
sdks

SDK — Go

vereid-go — context-aware, zero-magic Go SDK with full coverage of the VEREID API surface.

Last updated 2026-05-20

vereid-go is the official Go module. It is intentionally idiomatic: every call takes context.Context, returns typed structs + errors, and uses no init-time side effects. It depends only on the standard library.

Install

go get github.com/vereid/sdk-go@latest
import "github.com/vereid/sdk-go/vereid"

Quickstart

package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
 
    "github.com/vereid/sdk-go/vereid"
)
 
func main() {
    client := vereid.NewClient(os.Getenv("VEREID_API_KEY"))
 
    ctx := context.Background()
    profile, err := client.Social.Profiles.Get(ctx, "@mina")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s — tier %s\n", profile.DisplayName, profile.Verification.Tier)
 
    session, err := client.Verify.Sessions.Create(ctx, &vereid.CreateSessionInput{
        Tiers:     []string{"T1", "T2"},
        Reference: "user_42",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Send the user to:", session.HostedURL)
}

Options

client := vereid.NewClient(apiKey,
    vereid.WithBaseURL("https://api.vereid.com"),
    vereid.WithHTTPClient(myHTTPClient),
    vereid.WithUserAgent("myapp/1.4.2"),
    vereid.WithRetry(vereid.RetryConfig{
        MaxAttempts: 5,
        BaseDelay:   250 * time.Millisecond,
    }),
)

WithRetry honours the Retry-After header automatically; do not implement your own back-off on top.

Webhook verification

import "github.com/vereid/sdk-go/vereid/webhooks"
 
func handler(w http.ResponseWriter, r *http.Request) {
    raw, _ := io.ReadAll(r.Body)
    if !webhooks.Verify(raw, r.Header.Get("vereid-signature"), secret, 5*time.Minute) {
        http.Error(w, "bad signature", 400)
        return
    }
    var env webhooks.Envelope
    json.Unmarshal(raw, &env)
    switch env.Type {
    case "verification.completed":
        var data vereid.VerificationResult
        json.Unmarshal(env.Data, &data)
        // ...
    }
    w.WriteHeader(204)
}

Pagination

Every list endpoint exposes both a List method and an Iter method. Iter returns a stateful iterator that follows next_cursor automatically:

it := client.Social.Timeline.Iter(ctx, "@mina", nil)
for it.Next() {
    post := it.Item()
    fmt.Println(post.Body)
}
if err := it.Err(); err != nil {
    log.Fatal(err)
}

Errors

session, err := client.Verify.Sessions.Create(ctx, in)
var rateErr *vereid.RateLimitError
var valErr *vereid.ValidationError
switch {
case errors.As(err, &rateErr):
    time.Sleep(rateErr.RetryAfter)
case errors.As(err, &valErr):
    log.Printf("invalid: %s (req=%s)", valErr.Detail, valErr.RequestID)
case err != nil:
    return err
}

All errors implement error and carry the RFC 9457 problem document under .Problem along with .RequestID and .StatusCode.

OIDC helpers

The vereid/oidc subpackage provides PKCE helpers, JWKS caching, and token validation:

import "github.com/vereid/sdk-go/vereid/oidc"
 
verifier := oidc.NewVerifier(ctx, oidc.Config{
    Issuer:   "https://auth.vereid.com",
    Audience: clientID,
})
claims, err := verifier.Verify(ctx, rawIDToken)
fmt.Println(claims.VereidVerification.Tier)

The verifier caches JWKS with the Cache-Control headers from the JWKS endpoint and rotates seamlessly.

Context and cancellation

Every call respects ctx.Done(). Cancelling a long-running create-session call (e.g. while the user navigates away in your web app) aborts the in-flight HTTP request and returns context.Canceled.

Testing

client := vereid.NewTestClient(t)
client.Verify.Sessions.MockCreate(func(in *vereid.CreateSessionInput) (*vereid.Session, error) {
    return &vereid.Session{ID: "vs_test", Status: "pending"}, nil
})

The test client records every call for assertion via client.Calls().

Versioning

Strict semver via Go modules. Pin a major version in your go.mod. Breaking changes ship as v2/, v3/ etc. and are announced on the changelog.