Configuration

The Go SDK is configured via toggly.Config.

User context belongs to each request

Normal boolean evaluation fetches global definitions and evaluates with each request's user context. Pass identity, memberships and claims into that local evaluation; do not mutate a shared application's startup identity for each user. Optional remotely evaluated variants have a separate client-scoped context. Configure that fixed context before startup as shown below. It does not replace the request-local context used by ordinary boolean evaluation.

Required

• AppKey: your application key from Toggly
• Environment: environment name (e.g. Production, Staging)

client, err := toggly.NewClient(toggly.Config{
  AppKey:      os.Getenv("TOGGLY_APP_KEY"),
  Environment: os.Getenv("TOGGLY_ENV"),
})

Initial context for remote variants

client, err := toggly.NewClient(toggly.Config{
    AppKey: "YOUR_APP_KEY",
    Environment: "Production",
    EnableVariants: true,
    VariantIdentity: "user-123", // Stable ID for this variants client.
    VariantGroups: []string{"beta"}, // Memberships used by targeting rules.
    VariantClaims: map[string]string{"plan": "pro"}, // String rule attributes.
})
if err != nil {
    return err
}
defer client.Close()

The client copies groups and claims before its initial background refresh. Initialization is asynchronous; results become available after the first successful refresh. Use one variants client per fixed context. Do not call SetVariantIdentity on a shared client for each HTTP request. With EnableVariants: false, pass request-local toggly.Context to IsEnabled. In variants mode, the server supplies the enabled result and variant together.

Empty collections add no targeting values. Blank groups and empty claim names or values are omitted; claim names are sorted and limited to 20. Use separate groups, not commas inside a group name. Cached payloads and conditional validators match the complete context, endpoint, app and environment.

Common options

• BaseURL: defaults to https://app.toggly.io/ (gRPC usage and metrics)
• DefinitionsURL: defaults to https://definitions.toggly.io/ (HTTP definition fetches)
• RefreshInterval: background refresh period (default: 5 minutes)
• HTTPTimeout: timeout for refresh calls (default: 10 seconds)
• EnableUndefinedOnDevelopment: if true, unknown flags evaluate to true (useful for local dev)
• DisableEntityContextRegistration: if true, skip the startup PUT sdk/{appKey}/contexts catalog sync (entity evaluation still works; see Entity context)

client, err := toggly.NewClient(toggly.Config{
  AppKey:          "YOUR_APP_KEY",
  Environment:     "Production",
  BaseURL:         "https://app.toggly.io/",
  DefinitionsURL:  "https://definitions.toggly.io/",

  RefreshInterval: 2 * time.Minute,
  HTTPTimeout:     5 * time.Second,
})

Background refresh

The client starts its initial refresh asynchronously, then refreshes definitions in the background. Normally leave background refresh enabled. Disabling it also prevents the initial fetch and snapshot loading:

client, err := toggly.NewClient(toggly.Config{
  AppKey:                  "YOUR_APP_KEY",
  Environment:             "Production",
  DisableBackgroundRefresh: true,
})

There is no public manual refresh or wait-for-sync method. A successfully constructed client does not prove definitions are loaded. Use the status fields and loading/fallback guidance in Troubleshooting.

Session stickiness

SessionStore is optional. Use it if you want to cache evaluations per identity (or if you register custom non-deterministic filters and want stable decisions for a period of time):

client, err := toggly.NewClient(toggly.Config{
  AppKey:       "YOUR_APP_KEY",
  Environment:  "Production",
  SessionStore: session.NewMemoryStore(),
  SessionTTL:   30 * time.Minute,
})

Close / shutdown

Close the client exactly once from its owning component after request work stops, to stop background refresh and close optional gRPC connections. Do not close a shared client from individual request handlers. Close waits for the refresh goroutine and does not accept a cancellation context:

defer func() { _ = client.Close() }()