itglue

A Go client library for the IT Glue REST API. Provides typed access to 25+ resource types with a fluent query builder, automatic rate limiting, and a flexible asset embedding pattern for user-defined types.

Installation

go get github.com/scjalliance/itglue

Requires Go 1.26+.

Quick Start

client, err := itglue.NewClient(itglue.Config{
    APIKey: "your-api-key",
    Region: "us", // or "eu", "au"
})
if err != nil {
    log.Fatal(err)
}

// List organizations
result, err := client.Organizations.List(ctx, itglue.NewQuery().Limit(50))
if err != nil {
    log.Fatal(err)
}

for _, org := range result.Items {
    fmt.Printf("%d  %s\n", org.ID, org.Name)
}

Authentication

IT Glue uses API key authentication. Generate keys in Account > Settings > API Keys. Keys auto-revoke after 90 days of inactivity.

All requests include the x-api-key header and Content-Type: application/vnd.api+json automatically.

Regions

IT Glue operates in three regions:

Region	Base URL
US (default)	https://api.itglue.com
EU	https://api.eu.itglue.com
Australia	https://api.au.itglue.com

Set Region in the config, or override with BaseURL for testing.

Query Builder

Build JSON:API queries with a fluent interface:

query := itglue.NewQuery().
    Limit(100).
    Sort("name").
    Filter(itglue.Field("status").Eq("active")).
    OrganizationID(5678).
    Include("contacts", "locations")

result, err := client.Configurations.List(ctx, query)

Supported filter operator: Eq (equals). IT Glue filter keys use snake_case (e.g. organization_id, flexible_asset_type_id), even though response attribute keys are kebab-case.

Resources

The client covers the following IT Glue API resources:

Core Resources

Service	Type	Operations
Organizations	Organization	List, Get, Create, Update, Delete
Configurations	Configuration	List, Get, Create, Update, Delete
Contacts	Contact	List, Get, Create, Update, Delete
Passwords	Password	List, Get, Create, Update, Delete
Documents	Document	List, Get, Create, Update, Delete
Locations	Location	List, Get, Create, Update, Delete
Checklists	Checklist	List, Get, Create, Update, Delete
Users	User	List, Get, Create, Update, Delete
Groups	Group	List, Get, Create, Update, Delete

Flexible Assets

Service	Type	Operations
FlexibleAssets	User-defined	List, Get, Create, Update, Delete (generic)
FlexibleAssetTypes	FlexibleAssetType	List, Get, Create (with initial fields), Update
FlexibleAssetFields	FlexibleAssetField	ListByType, Get, Create, Update, Delete

IT Glue requires that flexible asset types be created together with at least one field (and at least one of those fields must have ShowInList=true). It also does not support deleting types — use Update with Enabled=false to retire one. Fields can be fully deleted.

Supporting Resources

Service	Type	Operations
ConfigurationTypes	ConfigurationType	List, Get, Create, Update
ConfigurationStatuses	ConfigurationStatus	List, Get, Create, Update
ContactTypes	ContactType	List, Get, Create, Update
OrganizationTypes	OrganizationType	List, Get, Create, Update
OrganizationStatuses	OrganizationStatus	List, Get, Create, Update
PasswordCategories	PasswordCategory	List, Get, Create, Update
PasswordFolders	PasswordFolder	List, Get, Create, Update, Delete
Manufacturers	Manufacturer	List, Get, Create, Update
Models	Model	List, Get, Create, Update
Domains	Domain	List, Get
Expirations	Expiration	List, Get
Countries	Country	List, Get
Regions	Region	List, Get

Flexible Assets

IT Glue flexible assets are user-defined asset types with custom fields. Define Go types by embedding BaseFlexibleAsset:

type ServerAsset struct {
    itglue.BaseFlexibleAsset
    ServerName  string `json:"server-name"`
    IPAddress   string `json:"ip-address"`
    Environment string `json:"environment"`
    CPUCores    int    `json:"cpu-cores"`
}

// Query servers with type safety
result, err := itglue.List[ServerAsset](client.FlexibleAssets, ctx,
    itglue.NewQuery().
        Filter(itglue.Field("organization_id").Eq(5678)).
        Filter(itglue.Field("flexible_asset_type_id").Eq(101)))

for _, server := range result.Items {
    fmt.Printf("%s: %s (%d cores)\n", server.ServerName, server.IPAddress, server.CPUCores)
}

// Create a new server asset
server := &ServerAsset{
    BaseFlexibleAsset: itglue.BaseFlexibleAsset{
        OrganizationID:      5678,
        FlexibleAssetTypeID: 101,
    },
    ServerName:  "web01",
    IPAddress:   "192.168.1.100",
    Environment: "production",
    CPUCores:    8,
}
created, err := itglue.Create[ServerAsset](client.FlexibleAssets, ctx, server)

Custom fields are stored in IT Glue's traits map. The library automatically merges traits into your struct fields during unmarshaling, and extracts them when creating/updating.

JSON tags on trait fields must use the exact trait key as defined in IT Glue (typically kebab-case like server-name). Filter keys, in contrast, use snake_case (e.g. filter[flexible_asset_type_id]=101).

Pagination

The idiomatic way to consume paginated results is with All, which returns a Go iterator:

for org, err := range client.Organizations.All(ctx, itglue.NewQuery().Limit(100)) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(org.Name)
}

Pages are fetched automatically as you iterate. Breaking early stops fetching.

For page-level control (metadata, manual navigation), use List:

result, err := client.Organizations.List(ctx, query)
fmt.Printf("Total: %d\n", result.Meta.TotalCount)

// Iterate items from this page onward
for org, err := range result.Iter(ctx) {
    if err != nil { break }
    process(org)
}

// Or collect all remaining pages into a slice
allOrgs, err := result.Collect(ctx)

IT Glue allows up to 1000 results per page.

Rate Limiting

The client automatically tracks API usage against IT Glue's limit of 3000 requests per 5-minute window. When the limit is approached, the client waits before sending the next request. The threshold defaults to 2900 (configurable via Config.RateLimit).

Error Handling

The library returns typed errors for different failure scenarios:

result, err := client.Configurations.Get(ctx, 99999)
if err != nil {
    switch e := err.(type) {
    case *itglue.AuthError:
        log.Fatal("Invalid API key")
    case *itglue.ForbiddenError:
        log.Printf("Permission denied: %v", e)
    case *itglue.NotFoundError:
        log.Printf("Resource %s not found", e.ResourceID)
    case *itglue.RateLimitError:
        log.Printf("Rate limited, retry after %v", e.RetryAfter)
    case *itglue.ValidationError:
        log.Printf("Validation error on %s: %s", e.Field, e.Reason)
    default:
        log.Printf("API error: %v", err)
    }
}

Transient errors (429, 5xx) are automatically retried with exponential backoff up to Config.MaxRetries times (default: 3).

Configuration

client, err := itglue.NewClient(itglue.Config{
    APIKey:         "your-api-key",       // Required
    Region:         "us",                  // Optional: us, eu, au (default: us)
    BaseURL:        "",                    // Optional: override base URL
    RateLimit:      2900,                  // Optional: requests per 5-min window
    MaxRetries:     3,                     // Optional: retry count for transient errors
    DefaultTimeout: 30 * time.Second,      // Optional: Timeout for the default http.Client (ignored when HTTPClient is set)
    HTTPClient:     customHTTPClient,      // Optional: custom http.Client (manages its own timeouts)
    UserAgent:      "my-app/1.0",          // Optional: override User-Agent header
})

API Version Compatibility

This client is developed against the IT Glue REST API following the JSON:API specification. Some endpoints or fields may vary between IT Glue releases.

Documentation

• IT Glue API Documentation