API Reference

Go SDK

The official Go client for the XtraSecurity API. Built with goroutine-safe caching, strict typing, and Zero-Trust injection.

Installation

>_Terminal

go get github.com/xtrasecurity/xtra-sdk-go

Configuration

The SDK provides a primary struct, Client. It accepts a ClientOptions struct during instantiation via NewClient().

>_Terminal

import (
    "time"
    "github.com/xtrasecurity/xtra-sdk-go/xtra"
)
 
// Initialize the client
// It will automatically use os.Getenv("XTRA_TOKEN") if available
client, err := xtra.NewClient(xtra.ClientOptions{
    ProjectID: "prj_123456789",
    CacheTTL:  60 * time.Second, // Cache secrets in-memory for 60 seconds
})
if err != nil {
    panic(err)
}

Option	Type	Default	Description
Token	`string`	`os.Getenv("XTRA_TOKEN")`	The API Token used for authentication.
ProjectID	`string`	`os.Getenv("XTRA_PROJECT_ID")`	The default project ID for all secret operations.
APIUrl	`string`	`https://www.xtrasecurity.in/api`	Override the base URL for self-hosted Enterprise instances.
Cache	`bool`	`true`	Enables in-memory caching (goroutine-safe).
CacheTTL	`time.Duration`	`30 * time.Second`	Time-to-live for cached secrets.

Core Methods

GetSecrets()

Fetches all secrets for a specific environment and branch, returning a map[string]string. This method is goroutine-safe and utilizes the RWMutex cache.

>_Terminal

// Fetch from production (main branch)
secrets, err := client.GetSecrets("production", nil)
if err != nil {
    panic(err)
}
fmt.Println(secrets["DATABASE_URL"])
 
// Fetch from a specific branch and bypass cache
opts := &xtra.SecretOptions{
    Branch:  "feature/new-ui",
    NoCache: true,
}
previewSecrets, err := client.GetSecrets("staging", opts)

Parameter	Type	Description
env	`string`	Required. The target environment (e.g. "production").
opts	`*SecretOptions`	Optional struct containing Branch, ProjectID, and NoCache settings. Pass `nil` for defaults.

InjectSecrets()

A convenience method that fetches secrets and immediately populates os.Environ() using os.Setenv().

>_Terminal

import "github.com/xtrasecurity/xtra-sdk-go/xtra"
 
client, _ := xtra.NewClient(xtra.ClientOptions{})
 
// Instantly inject secrets into os.Environ
err := client.InjectSecrets("production", &xtra.SecretOptions{
    ProjectID: "prj_123456789",
    Branch:    "feature/new-ui",
    Override:  true, // Overwrite existing local environment variables
})
 
// Now you can use them normally across your application
dbUrl := os.Getenv("DATABASE_URL")

ClearCache()

Safely flushes the in-memory secret cache across all goroutines.

>_Terminal

client.ClearCache()

Advanced API Access

For power users building custom internal tools, Client exposes the raw auto-generated service classes.

>_Terminal

import (
    "context"
    "github.com/xtrasecurity/xtra-sdk-go/xtra"
)
 
client, _ := xtra.NewClient(xtra.ClientOptions{})
 
// Access the raw auto-generated API classes for advanced management
project, resp, err := client.Projects.GetProject(context.Background(), "prj_123456789")
 
if err != nil {
    if xtraErr, ok := err.(*xtra.Error); ok {
        fmt.Printf("XtraSecurity API Error: %s\n", xtraErr.Message)
    }
}

Error Handling

The Go SDK uses standard Go error handling. Internal SDK errors can be type-asserted to *xtra.Error.