igsdk

A Go SDK for the Itential Automation Platform and Itential Automation Gateway. It provides idiomatic HTTP clients with automatic authentication, TTL-based re-authentication, structured logging with sensitive-data redaction, and context-aware request tracing.

Features

• Dual-client support - Separate PlatformClient and GatewayClient for the Itential Automation Platform and Gateway
• Automatic authentication - Basic Auth and OAuth 2.0 (Client Credentials) handled transparently on every request
• TTL-based re-authentication - Configurable token lifetimes with automatic re-auth before expiry
• Structured logging - Text and JSON loggers built on log/slog with optional sensitive-data redaction
• Context-aware tracing - Attach trace IDs and correlation fields to a context.Context; they appear in all SDK log entries for that request
• Concurrency-safe - Both clients are safe for use by multiple goroutines

Requirements

• Go 1.24+

Installation

go get github.com/itential/igsdk

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/itential/igsdk"
)

func main() {
    client, err := igsdk.NewPlatformClient("platform.example.com",
        igsdk.WithBasicAuth("admin", "password"),
    )
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Get(context.Background(), "/health/server", nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.StatusCode())
}

Usage

Platform Client

client, err := igsdk.NewPlatformClient("platform.example.com",
    igsdk.WithBasicAuth("admin", "password"),
    igsdk.WithTLS(true),
    igsdk.WithVerify(true),
    igsdk.WithTimeout(30 * time.Second),
    igsdk.WithTTL(15 * time.Minute),
)

Gateway Client

client, err := igsdk.NewGatewayClient("gateway.example.com",
    igsdk.WithBasicAuth("admin@itential", "password"),
)
// Requests are automatically prefixed with /api/v2.0
resp, err := client.Get(ctx, "/devices", nil)

OAuth Authentication (Platform only)

client, err := igsdk.NewPlatformClient("platform.example.com",
    igsdk.WithOAuth("my-client-id", "my-client-secret"),
)

Making Requests

All HTTP methods accept a context.Context, a path, optional query parameters, and optional per-request options:

// GET with query parameters
params := url.Values{"limit": []string{"10"}, "skip": []string{"0"}}
resp, err := client.Get(ctx, "/adapters", params)

// POST with a JSON payload
payload := map[string]any{"name": "MyAdapter", "type": "HTTP"}
resp, err := client.Post(ctx, "/adapters", nil, payload)

// PUT / PATCH / DELETE
resp, err := client.Put(ctx, "/adapters/123", nil, updates)
resp, err := client.Patch(ctx, "/adapters/123", nil, changes)
resp, err := client.Delete(ctx, "/adapters/123", nil)

Handling Responses

resp, err := client.Get(ctx, "/users/me", nil)
if err != nil {
    return err
}

// Parse JSON
var user map[string]any
if err := resp.JSON(&user); err != nil {
    return err
}

// Raw text
body := resp.Text()

// Status inspection
fmt.Println(resp.StatusCode())
fmt.Println(resp.IsSuccess())
fmt.Println(resp.IsError())

Error Handling

HTTP 4xx/5xx responses are returned as *igsdk.HTTPStatusError:

resp, err := client.Get(ctx, "/resource/missing", nil)
if err != nil {
    var httpErr *igsdk.HTTPStatusError
    if errors.As(err, &httpErr) {
        switch httpErr.StatusCode {
        case 404:
            fmt.Println("resource not found")
        case 401:
            fmt.Println("authentication failed")
        default:
            fmt.Printf("HTTP error: %s\n", httpErr.Status)
        }
    }
    return err
}

Logging

// Text logger (stderr, Info level by default)
logger := igsdk.NewLogger(
    igsdk.WithLogLevel(slog.LevelDebug),
    igsdk.WithLogOutput(os.Stdout),
)

// JSON logger
logger := igsdk.NewJSONLogger(igsdk.WithLogLevel(slog.LevelDebug))

client, err := igsdk.NewPlatformClient("platform.example.com",
    igsdk.WithLogger(logger),
)

Sensitive Data Redaction

scanner := igsdk.NewScanner()

logger := igsdk.NewLogger(igsdk.WithSensitiveDataRedaction(scanner))

client, err := igsdk.NewPlatformClient("platform.example.com",
    igsdk.WithLogger(logger),
    igsdk.WithScanner(scanner),
)

Request Tracing

Attach correlation fields to a context; the SDK includes them in every log entry for requests made with that context:

ctx = igsdk.LogContext(ctx, "request_id", reqID, "tenant", tenantID)
resp, err := client.Get(ctx, "/resources", nil)

Custom Request Headers

resp, err := client.Get(ctx, "/report", nil,
    igsdk.WithHeader("Accept", "application/xml"),
)

Documentation

• API Reference - Full GoDoc reference
• Contributing Guide - How to contribute to this project
• Changelog - Version history and release notes

Contributing

Contributions are welcome! Please read our Contributing Guide to get started.

Before contributing, you'll need to sign our Contributor License Agreement.

Support

• Bug Reports: Open an issue
• Questions: Start a discussion
• Maintainer: @privateip

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

---

Made with ❤️ by the Itential community