Documentation
¶
Overview ¶
Package workloadsecrets reads secrets from Delinea Workload Secrets Vault in a Go application.
Create one Client with New and reuse it: it is safe for concurrent use.
client, err := workloadsecrets.New(workloadsecrets.ClientOptions{
BaseURL: "https://example.delinea.app/workload-secrets",
TokenEndpoint: "https://example.delinea.app/identity/oauth2/token/xpmplatform",
ClientID: "my-service-user@example",
ClientSecret: os.Getenv("WS_CLIENT_SECRET"), // never from source code
})
if err != nil {
return err
}
secret, err := client.GetSecret(ctx, "ci/payments/api")
if err != nil {
return err
}
apiKey := secret.Data["apiKey"].(string)
Reading and minting ¶
Client.GetSecret reads the latest version of a secret and Client.GetSecretVersion reads one version. Client.MintSecret creates a new credential for a dynamic secret and returns it with its Lease; every call creates another credential, so mint once and reuse it until the lease is close to expiring. Dynamic secrets are available from the December 10, 2026 private preview.
Signing in ¶
By default the client signs in with a client ID and secret at TokenEndpoint. To use a token you already have, for example from workload identity federation, set ClientOptions.TokenSource instead.
Errors ¶
Failures from the API are *APIError and match ErrNotFound, ErrForbidden, ErrUnauthorized or ErrConflict with errors.Is. No error message contains a response body or a secret value.
Security ¶
- Only https addresses are accepted, except plain http to localhost, 127.0.0.1 or ::1 for local testing, so a token or the client secret is never sent in clear text.
- Printing a Secret shows its path, version and key names, never its values.
- Printing ClientOptions never shows the client secret.
- Redirects are followed to the same host only, so a token never reaches another host.
Behavior ¶
Reads are retried on 408, 429, 502, 503, 504 and connection failures, up to 4 attempts with backoff and jitter; a mint is retried only when the API proves it did nothing. Each attempt is limited to 15 seconds and the whole call to 60 seconds; change them with ClientOptions.Behavior.
The full API ¶
Client.API returns the generated client for every Workload Secrets Vault API operation, with the same credentials, retries and timeouts.
Example (Errors) ¶
Handle the usual failures with errors.Is, and read the details of any API error with errors.As.
client := newClient()
_, err := client.GetSecret(context.Background(), "ci/payments/api")
switch {
case err == nil:
// use the secret
case errors.Is(err, workloadsecrets.ErrNotFound):
fmt.Println("no secret at that path")
case errors.Is(err, workloadsecrets.ErrForbidden):
fmt.Println("signed in, but a policy does not allow this read")
default:
var apiErr *workloadsecrets.APIError
if errors.As(err, &apiErr) {
fmt.Println(apiErr.StatusCode, apiErr.ErrorCode)
}
log.Fatal(err)
}
Index ¶
- Variables
- func NewClient(options ClientOptions) (*generated.WorkloadSecretsApiClient, error)
- func NewHTTPClient(options ClientOptions) *http.Client
- type APIError
- type Behavior
- type Client
- func (c *Client) API() *generated.WorkloadSecretsApiClient
- func (c *Client) GetSecret(ctx context.Context, path string) (*Secret, error)
- func (c *Client) GetSecretVersion(ctx context.Context, path string, version int) (*Secret, error)
- func (c *Client) MintSecret(ctx context.Context, path string) (*Secret, error)
- type ClientOptions
- type Lease
- type RedirectNotFollowedError
- type Secret
- type TokenSource
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnauthorized = errors.New("workload secrets: unauthorized") // ErrForbidden: an authorization policy denies the call (403). ErrForbidden = errors.New("workload secrets: forbidden") // ErrNotFound: nothing exists at the path, or that version (404). ErrNotFound = errors.New("workload secrets: not found") // ErrConflict: the request conflicts with the current state (409), for example an engine that must be upgraded. ErrConflict = errors.New("workload secrets: conflict") )
Sentinel errors for the failures a caller usually handles. Test with errors.Is; an *APIError matches the one for its status code.
Functions ¶
func NewClient ¶
func NewClient(options ClientOptions) (*generated.WorkloadSecretsApiClient, error)
NewClient builds a WorkloadSecretsApiClient wired with retry and the tenant header, authenticated either via OAuth2 client-credentials (the default) or via options.TokenSource when set.
func NewHTTPClient ¶
func NewHTTPClient(options ClientOptions) *http.Client
NewHTTPClient builds the same authenticated (retry + tenant header + bearer/OAuth2) *http.Client NewClient wires internally, for callers that need to issue requests the generated SDK can't express (e.g. a multipart/form-data body) against the same tenant/credentials. It carries no base URL — callers resolve request URLs themselves.
Types ¶
type APIError ¶
type APIError struct {
StatusCode int
// ErrorCode is the API's machine-readable code (for example "secret_not_found"); empty when the response had no
// Problem Details body.
ErrorCode string
Title string
// contains filtered or unexported fields
}
APIError is an error response from the Workload Secrets API. Its message carries the status, the API's errorCode and title, never a response body or a secret value. Unwrap returns the generated client's error.
type Behavior ¶
type Behavior struct {
// PerAttemptTimeout bounds one attempt, including reading the response headers. Default 15 s.
PerAttemptTimeout time.Duration
// TotalTimeout bounds the whole call: every attempt and every wait between attempts. Default 60 s.
TotalTimeout time.Duration
}
Behavior tunes the SDK's resilience. A zero value keeps the default.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client reads secrets and mints dynamic credentials with one call each. Anything else the API offers is on API(), the generated client, which uses the same credentials, retries and timeouts.
func New ¶
func New(options ClientOptions) (*Client, error)
New builds a Client from options. It wires the same transport chain as NewClient: tenant header, retries that obey the API's retry-safety flags, the bearer token and same-origin redirects.
Example ¶
Sign in with a client ID and secret. The secret comes from the environment, never from source code.
client, err := workloadsecrets.New(workloadsecrets.ClientOptions{
BaseURL: "https://example.delinea.app/workload-secrets",
TokenEndpoint: "https://example.delinea.app/identity/oauth2/token/xpmplatform",
ClientID: "my-service-user@example",
ClientSecret: os.Getenv("WS_CLIENT_SECRET"),
})
if err != nil {
log.Fatal(err)
}
_ = client // create one client and reuse it
func (*Client) API ¶
func (c *Client) API() *generated.WorkloadSecretsApiClient
API returns the generated client, for the operations Client has no call for.
func (*Client) GetSecret ¶
GetSecret reads the latest version of the secret at path. Reading changes nothing. A dynamic secret holds no values to read: the API refuses it with a conflict, and MintSecret creates its credential. Failures from the API are *APIError and match ErrNotFound, ErrForbidden, ErrUnauthorized or ErrConflict with errors.Is.
Example ¶
Read the latest version of a secret and use one of its values.
client := newClient()
secret, err := client.GetSecret(context.Background(), "ci/payments/api")
if err != nil {
log.Fatal(err)
}
fmt.Println(secret) // safe: shows the path, version and key names, never the values
apiKey := secret.Data["apiKey"].(string)
_ = apiKey // use the value; never print or log it
func (*Client) GetSecretVersion ¶
GetSecretVersion reads one version of the secret at path. Otherwise it behaves like GetSecret.
Example ¶
Read one version of a secret.
client := newClient()
secret, err := client.GetSecretVersion(context.Background(), "ci/payments/api", 2)
if err != nil {
log.Fatal(err)
}
fmt.Println(secret.Version, secret.CreatedTime.Format(time.RFC3339))
func (*Client) MintSecret ¶
MintSecret creates a credential for the dynamic secret at path and returns it with its Lease. Every call creates another credential, so the call is never resent once the request may have reached the API (see the retry rules). A secret that is not dynamic is refused with a conflict. Dynamic secrets are available from the December 10, 2026 private preview. Failures from the API are *APIError and match ErrNotFound, ErrForbidden, ErrUnauthorized or ErrConflict with errors.Is.
Example ¶
Mint a database credential from a dynamic secret. Every call creates another credential, so mint once and reuse it until its lease is close to expiring. Dynamic secrets are available from the December 10, 2026 private preview.
client := newClient()
credential, err := client.MintSecret(context.Background(), "ci/payments/pg-db")
if err != nil {
log.Fatal(err)
}
if credential.Data["type"] == "database" {
username := credential.Data["username"].(string)
password := credential.Data["password"].(string)
_, _ = username, password // connect to the database with them
}
fmt.Println("expires", credential.Lease.ExpiresAt.Format(time.RFC3339))
type ClientOptions ¶
type ClientOptions struct {
BaseURL string
TenantID string
ClientID string
ClientSecret string
TokenEndpoint string
// TokenSource, when set, bypasses the ClientID/ClientSecret/TokenEndpoint
// OAuth2 client-credentials flow and supplies the bearer token directly —
// the seam a caller with its own token-acquisition flow (e.g. the CLI's
// device-code login) uses to feed NewClient a token it acquired itself.
TokenSource TokenSource
// Behavior overrides the default timeouts.
Behavior Behavior
// Transport is the base round tripper requests are finally sent through, for a proxy or custom TLS settings.
// Default http.DefaultTransport.
Transport http.RoundTripper
// Logger receives a debug record for each retry. Nil logs nothing. Records carry the method, path, attempt,
// wait, status and error text, never headers or bodies.
Logger *slog.Logger
}
ClientOptions is per-environment configuration for the Workload Secrets Public API SDK.
Example (TokenSource) ¶
Use a token you already have, for example from workload identity federation, instead of a client ID and secret.
client, err := workloadsecrets.New(workloadsecrets.ClientOptions{
BaseURL: "https://example.delinea.app/workload-secrets",
TokenSource: platformTokenSource{},
})
if err != nil {
log.Fatal(err)
}
_ = client
func (ClientOptions) GoString ¶
func (o ClientOptions) GoString() string
GoString is String, so %#v hides the client secret too.
func (ClientOptions) LogValue ¶
func (o ClientOptions) LogValue() slog.Value
LogValue keeps the client secret out of log/slog records.
func (ClientOptions) String ¶
func (o ClientOptions) String() string
String shows the options without the client secret, so printing or logging them never leaks it.
type RedirectNotFollowedError ¶
RedirectNotFollowedError is returned when the API answers with a redirect to a different origin. The request is not sent there, so neither the request nor its credentials leave the configured origin. Without an error, the generated client would treat the bodyless 3xx as a successful empty result.
func (*RedirectNotFollowedError) Error ¶
func (e *RedirectNotFollowedError) Error() string
type Secret ¶
type Secret struct {
Path string
// Version and CreatedTime describe the version a read returned. They are zero for a minted credential.
Version int
CreatedTime time.Time
// Data holds the secret's values as plain Go values, the way encoding/json decodes JSON. Nested objects are kept; a
// top-level key whose value is JSON null is absent. A minted credential holds "type" ("database" or "azure") and
// its strings: username and password, or tenantId, clientId and clientSecret.
Data map[string]any
// Lease is set by MintSecret: the credential in Data stops working at Lease.ExpiresAt. Nil for a static secret.
Lease *Lease
}
Secret is one version of a secret, or the credential a mint created. Printing it (fmt, or slog) shows the path, version and key names, never the values: read a value from Data explicitly.