SDK Reference

Go SDK

The secr-go package provides a Go client for the secr API. Built on net/http, it offers full type safety with Go structs and idiomatic error handling.

Installation

go get github.com/secr-dev/secr-go/secr

Requires Go 1.21+.

Quick Start

main.go

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/secr-dev/secr-go/secr"
)

func main() {
    client, err := secr.NewClient("secr_cli_...")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Pull secrets
    result, err := client.PullSecrets(ctx, "my-org", "my-project", "production", nil)
    if err != nil {
        log.Fatal(err)
    }
    for _, s := range result.Secrets {
        fmt.Printf("%s=%s\n", s.Key, s.Value)
    }

    // Set a secret
    _, err = client.SetSecret(ctx, "my-org", "my-project", "dev", "API_KEY", "sk-...")
    if err != nil {
        log.Fatal(err)
    }
}

Configuration

Use functional options to configure the client:

config.go

client, err := secr.NewClient(
    "secr_cli_...",
    secr.WithAPIURL("https://api.secr.dev"),  // Default
    secr.WithTimeout(30 * time.Second),        // Default
)

Option	Type	Required	Description
token	string	Yes	secr CLI token (secr_cli_...), passed as first argument
WithAPIURL	Option	https://api.secr.dev	API base URL
WithTimeout	Option	30s	Request timeout as time.Duration

API Reference

All methods take a context.Context as the first argument for cancellation and timeout support.

PullSecrets(ctx, org, project, env, opts)

Pull decrypted secrets for an environment.

Example

result, err := client.PullSecrets(ctx, "org", "proj", "production", &secr.PaginationOpts{
    Limit:  50,
    Offset: 0,
    Search: "DB_",
})
// result.Secrets -- []Secret: Key, Value, Description, Version, UpdatedAt
// result.Pagination -- *PaginationInfo: Limit, Offset, Total

ListKeys(ctx, org, project, env, opts)

List secret key names without values.

Example

result, err := client.ListKeys(ctx, "org", "proj", "dev", nil)
// result.Keys -- []SecretMeta: Key, Description, Version, UpdatedAt

SetSecret(ctx, org, project, env, key, value)

Create or update a single secret.

Example

result, err := client.SetSecret(ctx, "org", "proj", "dev", "DB_URL", "postgres://...")
// result.Key, result.Version

BulkSetSecrets(ctx, org, project, env, secrets)

Set multiple secrets at once.

Example

result, err := client.BulkSetSecrets(ctx, "org", "proj", "dev", []secr.SecretInput{
    {Key: "A", Value: "1"},
    {Key: "B", Value: "2"},
})
// result.Created, result.Updated, result.Total

DeleteSecret(ctx, org, project, env, key)

Soft-delete a secret.

Example

result, err := client.DeleteSecret(ctx, "org", "proj", "dev", "OLD_KEY")
// result.Deleted, result.Key

PromoteSecrets(ctx, org, project, opts)

Copy secrets between environments.

Example

result, err := client.PromoteSecrets(ctx, "org", "proj", secr.PromoteOpts{
    FromEnv:   "staging",
    ToEnv:     "production",
    Overwrite: true,
})
// result.Promoted, result.Created, result.Updated, result.Skipped

ListTemplates(ctx, org, project)

List secret templates for a project.

Example

result, err := client.ListTemplates(ctx, "org", "proj")
// result.Templates -- []Template: ID, Key, Description, Required, CreatedAt

ValidateTemplate(ctx, org, project, env)

Check if an environment has all required secrets.

Example

result, err := client.ValidateTemplate(ctx, "org", "proj", "production")
// result.Valid, result.Missing, result.Extra

Error Handling

API errors can be unwrapped to *secr.APIError using errors.As:

errors.go

result, err := client.PullSecrets(ctx, "org", "proj", "dev", nil)
if err != nil {
    var apiErr *secr.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.Message)    // Human-readable message
        fmt.Println(apiErr.StatusCode) // HTTP status (0 for network errors)
        fmt.Println(apiErr.Code)       // Error code: "unauthorized", "not_found", etc.
    }
}

Field	Type	Description
Message	string	Human-readable error message
StatusCode	int	HTTP status code (0 for network errors)
Code	string	Error code: "unauthorized", "not_found", etc.

Types

All response types are Go structs:

Struct	Fields
Secret	Key, Value, Description, Version, UpdatedAt
SecretMeta	Key, Description, Version, UpdatedAt
PaginationInfo	Limit, Offset, Total
PullSecretsResult	Secrets, Pagination
ListKeysResult	Keys, Pagination
SetSecretResult	Key, Version
BulkSetSecretsResult	Created, Updated, Total
DeleteSecretResult	Deleted, Key
PromoteResult	Promoted, Created, Updated, Skipped
Template	ID, Key, Description, Required, CreatedAt
TemplateValidation	Valid, Missing, Extra

Start building with the Go SDK

go get github.com/secr-dev/secr-go/secr

Create Free Account Back to Docs