Authentication

Configure API key authentication, environment variables, and custom headers for the Go SDK.

Authenticate with an API key or a bearer token. NewClient returns an error if neither is configured.

​

API Key via Option

The most explicit way to authenticate is passing WithAPIKey when creating the client.

client, err := phala.NewClient(
    phala.WithAPIKey("phak_your_api_key"),
)
if err != nil {
    log.Fatal(err)
}

​

API Key via Environment Variable

For production deployments, storing the key in an environment variable is the standard approach. The SDK reads PHALA_CLOUD_API_KEY automatically when no explicit key is provided.

export PHALA_CLOUD_API_KEY="phak_your_api_key"

// No WithAPIKey needed — reads from PHALA_CLOUD_API_KEY
client, err := phala.NewClient()
if err != nil {
    log.Fatal(err) // Fails if env var is also unset
}

If you pass WithAPIKey explicitly, it always takes priority over the environment variable.

​

Bearer token and workspace

Use WithBearerToken for bearer credentials, including an OIDC token, and WithWorkspace to select a workspace by slug. The SDK also reads PHALA_OIDC_TOKEN and PHALA_CLOUD_WORKSPACE. An API key takes precedence over a bearer token when both are configured. This also applies to credentials supplied with WithHeader: if the final request has an API key, the SDK removes its authorization header.

client, err := phala.NewClient(
    phala.WithBearerToken(os.Getenv("PHALA_OIDC_TOKEN")),
    phala.WithWorkspace("my-workspace"),
)
if err != nil {
    log.Fatal(err)
}

​

RevokeSelfToken

DELETE /tokens/self

client.RevokeSelfToken(ctx) revokes the API token used for the request. The token stops working immediately and cannot be restored.

​

Custom Base URL

You can override the API endpoint with WithBaseURL or the PHALA_CLOUD_API_PREFIX environment variable. The SDK defaults to https://cloud-api.phala.com/api/v1.

client, err := phala.NewClient(
    phala.WithAPIKey("phak_your_api_key"),
    phala.WithBaseURL("https://custom-api.example.com/api/v1"),
)

The environment variable takes effect when the configured URL is the SDK default, including when that default is passed explicitly.

​

Custom Headers

Use WithHeader to attach additional headers to every request. This is useful for tracing, correlation IDs, or internal routing.

client, err := phala.NewClient(
    phala.WithAPIKey("phak_your_api_key"),
    phala.WithHeader("X-Request-ID", "trace-abc123"),
    phala.WithHeader("X-Custom-Header", "my-value"),
)

Each call to WithHeader adds one header. You can call it multiple times to set several headers.

​

API Versioning

The SDK sends an API version header with every request. The default is "2026-06-23". Override it if you need an older response shape.

client, err := phala.NewClient(
    phala.WithAPIKey("phak_your_api_key"),
    phala.WithAPIVersion("2026-05-22"),
)

​

Custom HTTP Client

For advanced scenarios like custom TLS configuration, proxies, or instrumented transports, pass your own *http.Client with WithHTTPClient.

transport := &http.Transport{
    TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS13},
}
httpClient := &http.Client{Transport: transport}

client, err := phala.NewClient(
    phala.WithAPIKey("phak_your_api_key"),
    phala.WithHTTPClient(httpClient),
)

WithHTTPClient copies the provided client. WithTimeout modifies the SDK’s copy, not the original client.

​

User Agent

The SDK sends a User-Agent header like phala-cloud-sdk-go/0.3.0 by default. Override it to identify your application in server logs.

client, err := phala.NewClient(
    phala.WithAPIKey("phak_your_api_key"),
    phala.WithUserAgent("my-automation/2.0"),
)

​

Resolution Priority

The client resolves configuration in this order (first match wins):

1. Explicit option passed to NewClient (e.g., WithAPIKey, WithBaseURL)
2. Environment variable (PHALA_CLOUD_API_KEY, PHALA_CLOUD_API_PREFIX)
3. Built-in default (base URL: https://cloud-api.phala.com/api/v1)