Quickstart, Go

Prerequisites

• Go 1.22 or newer

• A Verdifax orchestrator. The examples use a self-hosted one at http://localhost:9090, which needs access to the private image (see Quickstart, Docker). Without that access, use the hosted API at https://api.verdifax.com with an API key, issued after an access request at verdifax.com/request, and replace http://localhost:9090 with it below.

• An API key. On a self-hosted orchestrator, provision one. On a deployment where no key has ever been created, mint the first one with admin scope (a key minted without it is customer scope, which gets 403 on the /admin/* calls, and creating it ends open mode):

  curl -X POST http://localhost:9090/admin/keys \
    -H "Content-Type: application/json" \
    -d '{"name": "go-quickstart", "scope": "admin", "confirm_admin_scope": true}'
  

  The server answers HTTP 201, and the response carries the secret once; store it as VERDIFAX_API_KEY in your environment. Once any key has been created, POST /admin/keys requires an admin key in the X-Verdifax-Key header. See Authentication.

1. Install

go get github.com/Verdifax/verdifax-sdk-go

2. Three lines (well, five, with the imports)

package main

import (
    "context"
    "fmt"
    "log"
    "strings"

    "github.com/Verdifax/verdifax-sdk-go"
)

func main() {
    client, err := verdifax.FromEnv()
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Attest(context.Background(), &verdifax.AttestRequest{
        PayloadText:        "hello verdifax",
        ProgramID:          strings.Repeat("a", 64),
        RouteID:            "route-test",
        RegistryRecordHash: strings.Repeat("b", 64),
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(res.Manifest.ManifestHash)
}

FromEnv() reads VERDIFAX_BASE_URL (default https://api.verdifax.com), VERDIFAX_API_KEY, and the optional VERDIFAX_TIMEOUT_MS / VERDIFAX_MAX_RETRIES knobs. Drop the call in favor of verdifax.NewClient(verdifax.Config{...}) if you'd rather pass config explicitly.

3. Verify

The whole point of the manifest hash is that it re-derives from the run's sealed fields. The orchestrator's verify endpoint recomputes the seal from the stored manifest fields and reports whether it matches:

v, err := client.VerifyRun(context.Background(), res.RunID)
if err != nil {
    log.Fatal(err)
}
if v.Verified {
    fmt.Println("✓ Stored manifest fields recompute to the recorded hash.")
}

4. Attest a Claude / OpenAI response

If you're sealing AI output text rather than arbitrary bytes, the SDK ships convenience helpers that wire the response into the AIVP governance pipeline for you:

res, err := client.AttestClaudeResponse(ctx,
    programID,            // 64-hex SHA-256 of your program identity
    "support-conversation",
    registryRecordHash,   // 64-hex registry record
    "What is 2+2?",       // user prompt
    "2+2 equals 4.",      // Claude's response
)

The response text becomes the input to AIVP; the resulting PIA hash binds into the manifest. See AIVP for the deeper integration story.

5. Error handling

The SDK throws typed errors so callers can errors.As to discriminate:

import "errors"

run, err := client.GetRun(ctx, 142)
if err != nil {
    var nf *verdifax.NotFoundError
    var auth *verdifax.AuthError
    switch {
    case errors.As(err, &nf):
        // run doesn't exist (or belongs to a different key)
    case errors.As(err, &auth):
        // missing or invalid API key
    default:
        // every other non-2xx, APIError carries Status + Path
    }
}

What this SDK covers

21 public methods spanning the canonical operations and the key, erasure and DCAE administrative endpoints (not every admin endpoint):

Idempotent GETs that hit a transient failure (502 / 503 / 504 / 429) are retried with exponential backoff + full jitter (default 3 retries; configurable). Non-idempotent methods (POST / PUT / DELETE) are NOT retried, replay is the caller's responsibility.

Next steps

• Federation & multi-tenancy, how multiple organizations share a single deployment.
• Troubleshooting, common errors and their resolutions.
• Verify a bundle, offline verification of a run's audit bundle with the open-source verdifax-verify.