Go SDK

Official Go SDK for KeyEnv with full type safety.

Installation

go get github.com/keyenv/go-sdk

Quick Start

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/keyenv/go-sdk"
)

func main() {
    client, err := keyenv.New(keyenv.Config{
        Token: os.Getenv("KEYENV_TOKEN"),
    })
    if err != nil {
        panic(err)
    }

    ctx := context.Background()

    // Load secrets into environment
    if _, err := client.LoadEnv(ctx, "your-project-id", "production"); err != nil {
        panic(err)
    }

    fmt.Println(os.Getenv("DATABASE_URL"))
}

Initialize the Client

client, err := keyenv.New(keyenv.Config{
    Token:    "your-service-token",
    Timeout:  30 * time.Second, // optional, default 30s
    CacheTTL: 5 * time.Minute,  // optional, default disabled
})

Loading Secrets

Load into Environment

The simplest way to use secrets in your application:

ctx := context.Background()
count, err := client.LoadEnv(ctx, "project-id", "production")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Loaded %d secrets\n", count)

// Now use them
fmt.Println(os.Getenv("DATABASE_URL"))

Export as Map

Get secrets as a map:

secrets, err := client.ExportSecretsAsMap(ctx, "project-id", "production")
if err != nil {
    log.Fatal(err)
}
fmt.Println(secrets["DATABASE_URL"])

Export with Metadata

Get secrets with full metadata:

secrets, err := client.ExportSecrets(ctx, "project-id", "production")
if err != nil {
    log.Fatal(err)
}
for _, secret := range secrets {
    fmt.Printf("%s=%s\n", secret.Key, secret.Value)
}

Managing Secrets

Get a Single Secret

secret, err := client.GetSecret(ctx, "project-id", "production", "DATABASE_URL")
if err != nil {
    log.Fatal(err)
}
fmt.Println(secret.Value)

Set a Secret

Creates or updates a secret:

err := client.SetSecret(ctx, "project-id", "production", "API_KEY", "sk_live_...")
if err != nil {
    log.Fatal(err)
}

// With description
description := "Production API key"
err = client.SetSecretWithDescription(ctx, "project-id", "production", "API_KEY", "sk_live_...", &description)

Delete a Secret

err := client.DeleteSecret(ctx, "project-id", "production", "OLD_KEY")

Bulk Operations

Bulk Import

result, err := client.BulkImport(ctx, "project-id", "development", []keyenv.SecretInput{
    {Key: "DATABASE_URL", Value: "postgres://localhost/mydb"},
    {Key: "REDIS_URL", Value: "redis://localhost:6379"},
}, keyenv.BulkImportOptions{Overwrite: true})

fmt.Printf("Created: %d, Updated: %d\n", result.Created, result.Updated)

Generate .env File

content, err := client.GenerateEnvFile(ctx, "project-id", "production")
if err != nil {
    log.Fatal(err)
}
os.WriteFile(".env", []byte(content), 0644)

Projects & Environments

List Projects

projects, err := client.ListProjects(ctx)
for _, project := range projects {
    fmt.Printf("%s (%s)\n", project.Name, project.ID)
}

Get Project Details

project, err := client.GetProject(ctx, "project-id")
fmt.Printf("Project: %s\n", project.Name)
for _, env := range project.Environments {
    fmt.Printf("  - %s\n", env.Name)
}

Environment Permissions

Manage who can access secrets in each environment.

List Permissions

permissions, err := client.ListPermissions(ctx, "project-id", "production")
if err != nil {
    log.Fatal(err)
}
for _, perm := range permissions {
    fmt.Printf("%s: %s\n", perm.UserEmail, perm.Role)
}

Set Permission

// Grant write access to a user
err := client.SetPermission(ctx, "project-id", "production", "user-id", "write")
if err != nil {
    log.Fatal(err)
}

Delete Permission

err := client.DeletePermission(ctx, "project-id", "production", "user-id")

Get My Permissions

result, err := client.GetMyPermissions(ctx, "project-id")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Is team admin: %v\n", result.IsTeamAdmin)
for _, perm := range result.Permissions {
    fmt.Printf("%s: %s (can_write: %v)\n", perm.EnvironmentName, perm.Role, perm.CanWrite)
}

Bulk Set Permissions

err := client.BulkSetPermissions(ctx, "project-id", "production", []keyenv.PermissionInput{
    {UserID: "user-1", Role: "write"},
    {UserID: "user-2", Role: "read"},
})

Project Defaults

// Get default permissions
defaults, err := client.GetProjectDefaults(ctx, "project-id")
for _, d := range defaults {
    fmt.Printf("%s: %s\n", d.EnvironmentName, d.DefaultRole)
}

// Set default permissions for new team members
err = client.SetProjectDefaults(ctx, "project-id", []keyenv.ProjectDefaultInput{
    {EnvironmentName: "development", DefaultRole: "write"},
    {EnvironmentName: "staging", DefaultRole: "read"},
    {EnvironmentName: "production", DefaultRole: "none"},
})

Error Handling

secret, err := client.GetSecret(ctx, "project-id", "production", "MISSING_KEY")
if err != nil {
    var keyenvErr *keyenv.Error
    if errors.As(err, &keyenvErr) {
        switch keyenvErr.Status {
        case 401:
            log.Fatal("Invalid or expired token")
        case 403:
            log.Fatal("Access denied")
        case 404:
            log.Fatal("Secret not found")
        default:
            log.Fatalf("Error %d: %s", keyenvErr.Status, keyenvErr.Message)
        }
    }
}

Caching

Enable caching for better performance in serverless environments:

client, _ := keyenv.New(keyenv.Config{
    Token:    os.Getenv("KEYENV_TOKEN"),
    CacheTTL: 5 * time.Minute,
})

ctx := context.Background()

// Cached for 5 minutes
secrets, _ := client.ExportSecrets(ctx, "project-id", "production")

// Clear cache manually
client.ClearCache("project-id", "production")

API Reference

Constructor Options

Option	Type	Required	Default	Description
`Token`	`string`	Yes	-	Service token
`Timeout`	`time.Duration`	No	`30s`	Request timeout
`CacheTTL`	`time.Duration`	No	`0`	Cache TTL (0 = disabled)

Methods

All methods require a context.Context as the first parameter.

Method	Description
`GetCurrentUser(ctx)`	Get current user/token info
`ListProjects(ctx)`	List all accessible projects
`GetProject(ctx, id)`	Get project with environments
`ListEnvironments(ctx, projectId)`	List environments
`ListSecrets(ctx, projectId, env)`	List secret keys (no values)
`ExportSecrets(ctx, projectId, env)`	Export secrets with values
`ExportSecretsAsMap(ctx, projectId, env)`	Export as map
`GetSecret(ctx, projectId, env, key)`	Get single secret
`SetSecret(ctx, projectId, env, key, value)`	Create or update secret
`DeleteSecret(ctx, projectId, env, key)`	Delete secret
`BulkImport(ctx, projectId, env, secrets, opts)`	Bulk import secrets
`LoadEnv(ctx, projectId, env)`	Load secrets into os.Environ
`GenerateEnvFile(ctx, projectId, env)`	Generate .env file content
`ClearCache(projectId, env)`	Clear cached secrets (no ctx)
`ListPermissions(ctx, projectId, env)`	List environment permissions
`SetPermission(ctx, projectId, env, userId, role)`	Set user permission
`DeletePermission(ctx, projectId, env, userId)`	Remove user permission
`GetMyPermissions(ctx, projectId)`	Get current user's permissions
`BulkSetPermissions(ctx, projectId, env, perms)`	Bulk set permissions
`GetProjectDefaults(ctx, projectId)`	Get default permissions
`SetProjectDefaults(ctx, projectId, defaults)`	Set default permissions

Examples

HTTP Server

package main

import (
    "context"
    "log"
    "net/http"
    "os"

    "github.com/keyenv/go-sdk"
)

func main() {
    client, _ := keyenv.New(keyenv.Config{
        Token: os.Getenv("KEYENV_TOKEN"),
    })

    // Load secrets before starting server
    client.LoadEnv(context.Background(), os.Getenv("KEYENV_PROJECT"), "production")

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("OK"))
    })

    log.Fatal(http.ListenAndServe(":"+os.Getenv("PORT"), nil))
}

Lambda Function

package main

import (
    "context"
    "os"
    "time"

    "github.com/aws/aws-lambda-go/lambda"
    "github.com/keyenv/go-sdk"
)

var client *keyenv.Client

func init() {
    client, _ = keyenv.New(keyenv.Config{
        Token:    os.Getenv("KEYENV_TOKEN"),
        CacheTTL: 5 * time.Minute, // Cache across warm invocations
    })
    client.LoadEnv(context.Background(), os.Getenv("KEYENV_PROJECT"), "production")
}

func handler(ctx context.Context) (string, error) {
    return os.Getenv("API_KEY"), nil
}

func main() {
    lambda.Start(handler)
}

Go SDK

On this page