Version: 1.0.0

SDK Configuration Options

The Aruba Cloud SDK for Go is configured using a fluent API that allows you to chain option setters to build a client configuration. This guide details all available options, grouped by topic.

Getting Started

The easiest way to configure the client is by using DefaultOptions, which provides a production-ready setup for the most common use case (Client Credentials authentication).

Option Setter	Description	Notes
`DefaultOptions(clientID, clientSecret)`	Creates a standard configuration for the production environment using your API Client ID and Secret.	This is the recommended starting point for most applications. It sets the production API and token URLs and configures authentication.
`NewOptions()`	Creates a new, empty configuration builder. You must manually configure all required settings, including authentication.	Use this if you need complete control over the configuration from scratch.

General Configuration

Option Setter	Description	Notes
`WithBaseURL(baseURL)`	Overrides the default Aruba Cloud API URL.	The default is `https://api.arubacloud.com`. You should only change this if you need to target a different environment.
`WithDefaultBaseURL()`	A helper that sets the API URL to the production default.	Called by `DefaultOptions()`.

Authentication

Authentication is a critical part of the configuration. You must choose one of the following methods.

Option Setter	Description	Notes
`WithDefaultTokenManagerSchema(clientID, clientSecret)`	Configures standard Client Credentials auth with the default token issuer URL and no persistent caching. Called internally by `DefaultOptions()`.	Use this when you want to reset the token manager to its factory defaults before applying selective overrides.
`WithClientCredentials(clientID, clientSecret)`	(Recommended) Configures the SDK to use the OAuth2 Client Credentials flow. The SDK will automatically manage fetching and renewing the access token.	Mutual Exclusion: Cannot be used with `WithToken()` or `WithVaultCredentialsRepository()`. This is the standard and most secure method for service-to-service authentication.
`WithToken(token)`	Configures the SDK to use a static, pre-existing OAuth2 access token.	Mutual Exclusion: Cannot be used with any other authentication or token issuer option. Warning: The SDK will not renew this token. Once it expires, all API calls will fail. This method is only recommended for short-lived clients or simple, atomic scripts.
`WithVaultCredentialsRepository(...)`	Configures the SDK to fetch the `clientID` and `clientSecret` from a HashiCorp Vault instance. The SDK will then use these credentials to manage the access token.	Mutual Exclusion: Cannot be used with `WithClientCredentials()` or `WithToken()`. Parameters: `vaultURI`, `kvMount`, `kvPath`, `namespace`, `rolePath`, `roleID`, `secretID`.
`WithTokenIssuerURL(url)`	Overrides the default URL for the OAuth2 token endpoint.	The default is `https://mylogin.aruba.it/auth/realms/cmp-new-apikey/protocol/openid-connect/token`. You should only change this if you need to target a different authentication endpoint.
`WithSecurityScopes(scopes ...)`	Sets the security scopes to be claimed during authentication.	Replaces any previously set scopes.
`WithAdditionalSecurityScopes(scopes ...)`	Appends additional security scopes to the existing list.	Does not override existing scopes.

Token Caching (Optional)

For improved performance and resilience, the SDK can cache the access token to an external store. This is highly recommended for production applications to avoid fetching a new token on every startup.

Option Setter	Description	Notes
`WithRedisTokenRepositoryFromURI(redisURI)`	Configures a Redis instance as a persistent cache for the access token using a full URI.	Mutual Exclusion: Cannot be used with `WithFileTokenRepository...` options. The URI format is `redis://<user>:<pass>@<host>:<port>/<db>`.
`WithRedisTokenRepositoryFromStandardURI()`	Configures Redis caching using the standard local URI (`redis://admin:admin@localhost:6379/0`).	Shortcut for local development. Does not set the expiration drift; pair with `WithStandardTokenExpirationDriftSeconds()` or use `WithStandardRedisTokenRepository()`.
`WithFileTokenRepositoryFromBaseDir(baseDir)`	Configures a local directory to store the access token in a JSON file.	Mutual Exclusion: Cannot be used with `WithRedisTokenRepository...` options. The SDK process must have read/write permissions to the specified directory.
`WithFileTokenRepositoryFromStandardBaseDir()`	Configures file caching in `/tmp/sdk-go`.	Shortcut for local development. Does not set the expiration drift; pair with `WithStandardTokenExpirationDriftSeconds()` or use `WithStandardFileTokenRepository()`.
`WithTokenExpirationDriftSeconds(seconds)`	Sets a safety buffer (in seconds) to treat a token as expired before it actually does.	This prevents race conditions where the SDK uses a token that expires just before the API request completes. The default is 300 seconds (5 minutes). This option has no effect if a caching mechanism (Redis or File) is not configured.
`WithStandardTokenExpirationDriftSeconds()`	Sets the expiration drift to 300 seconds (5 minutes).	Equivalent to `WithTokenExpirationDriftSeconds(300)`.
`WithStandardRedisTokenRepository()`	Helper to configure Redis caching on `localhost:6379` and sets the standard expiration drift (300s).	A convenient shortcut for local development.
`WithStandardFileTokenRepository()`	Helper to configure file caching in `/tmp/sdk-go` and sets the standard expiration drift (300s).	A convenient shortcut for local development.

Logging

Logging is disabled by default.

Option Setter	Description	Notes
`WithDefaultLogger()`	Resets the logger to the SDK default (no logs). Called by `DefaultOptions()`.	Use this when you want to explicitly reset logging after having configured a custom logger.
`WithNoLogs()`	Disables all SDK logging.	This is the default behavior.
`WithNativeLogger()`	Enables the SDK's built-in logger, which uses the standard `log` package.	Useful for basic debugging.
`WithLoggerType(loggerType)`	A more general function to set the logger type.	`loggerType` can be `LoggerNoLog` or `LoggerNative`.
`WithCustomLogger(logger)`	Injects a custom logger that conforms to the `ports/logger.Logger` interface.	Allows integration with your application's logging framework (e.g., Logrus, Zap). Setting this automatically sets the logger type to `loggerCustom`.

HTTP Client Identity

The SDK automatically sets a User-Agent header on every outbound request so that API access logs can be attributed to the SDK version. By default the header value is sdk-go@<version> (e.g. sdk-go@1.0.0), derived from the aruba.Version constant defined in pkg/aruba/version.go.

Option Setter	Description	Notes
`WithUserAgent(ua)`	Overrides the default `User-Agent` header value sent with every request.	Use this when building a tool on top of the SDK and you want the API logs to show your tool's identity instead of (or in addition to) the raw SDK version. Example: `WithUserAgent("acloud-cli@1.0.0")`.

Advanced / Custom Dependencies

These options are for advanced use cases where you need to inject your own custom components into the SDK's workflow.

Option Setter	Description	Notes
`WithCustomHTTPClient(client)`	Injects a pre-configured `*http.Client`.	Useful for setting custom timeouts, transport, or other HTTP-level configurations.
`WithCustomMiddleware(middleware)`	Injects a custom middleware that conforms to the `ports/interceptor.Interceptor` interface.	Allows you to add custom logic (like request/response logging or tracing) into the SDK's HTTP call chain. The SDK's authentication middleware will be automatically bound to the end of your custom middleware chain.

Getting Started​

General Configuration​

Authentication​

Token Caching (Optional)​

Logging​

HTTP Client Identity​

Advanced / Custom Dependencies​