Skip to main content
Each recipe includes the problem, solution code, and rationale. The recipes that call HTTP APIs use the SDK’s uhttp package. It works in two layers:
  1. Credentials build an *http.Client that authenticates for you. uhttp.NewBearerAuth, NewBasicAuth, NewOAuth2ClientCredentials, NewOAuth2JWT, and NewOAuth2RefreshToken each return a value with a GetClient(ctx) method.
  2. BaseHttpClient wraps that client. It builds requests, sends them, and turns HTTP errors into the gRPC status codes that the SDK’s retry logic understands.
Declare every credential as a configuration field with field.WithIsSecret(true). See Configuration schema reference.

API key or bearer token

Problem: Connect to an API that expects a token in the Authorization: Bearer header. Solution:
Why: NewBearerAuth adds the token to every request. Do reads and closes the response body and decodes JSON for you. When the API returns an error status, Do returns an error with the matching gRPC code, such as Unavailable for 429 and 5xx responses, so the SDK can retry. uhttp doesn’t retry requests itself, and it doesn’t limit your request rate unless you add uhttp.WithRateLimiter(rate, per).

API key in a custom header

Problem: The API reads its key from a header other than Authorization. Solution: Set the header on each request:
Build the client with uhttp.NewClient(ctx) instead of an authenticated one, and wrap it with NewBaseHttpClientWithContext as in the previous recipe. Why: Headers are a per-request option, so you can vary them by call.

HTTP basic authentication

Problem: The API uses a username and password. Solution:

OAuth2 client credentials

Problem: Exchange a client ID and secret for an access token. Solution:
Why: The client refreshes tokens automatically, so you don’t manage expiry. Because it goes through uhttp, failures from the token endpoint also map to gRPC codes: authentication failures become Unauthenticated or PermissionDenied, and outages become Unavailable. The plain clientcredentials package from golang.org/x/oauth2 also works, but it bypasses these error codes. If the API gives you a refresh token and an access token, use uhttp.NewOAuth2RefreshToken with the client ID and secret, redirect URI, token URL, tokens, and scopes.

JWT service account (Google-style)

Problem: Authenticate with a service account JSON key file. Solution:
Why: Domain-wide delegation requires impersonating a domain admin. The Subject field names the user to impersonate.

LDAP bind

Problem: Connect to Active Directory or an LDAP server. Solution:
Why: LDAP requires a bind before any query. A simple bind uses a distinguished name and password. To authenticate with a TLS client certificate instead, connect with a client certificate and call conn.ExternalBind(), which uses SASL EXTERNAL. It doesn’t use Kerberos. Kerberos (GSSAPI) binds need a separate package from the go-ldap project.