Authentication

Credential Pairing

ClientBuilder enforces paired credentials:

• both api_key and secret_key must be present
• or both must be omitted
• ClientBuilder::build() rejects blank, whitespace-only, and HTTP header-invalid values before the client is constructed

Supplying only one side is an invalid configuration error.

The primary application path is explicit builder credentials:

use alpaca_data::Client;

let client = Client::builder()
    .api_key(std::env::var("APCA_API_KEY_ID").expect("APCA_API_KEY_ID is required"))
    .secret_key(std::env::var("APCA_API_SECRET_KEY").expect("APCA_API_SECRET_KEY is required"))
    .build()?;
# let _ = client;
# Ok::<(), alpaca_data::Error>(())

Optional Environment Helpers

When a service already injects credentials through process environment, ClientBuilder can load the pair directly:

use alpaca_data::Client;

let client = Client::builder()
    .credentials_from_env()?
    .build()?;
# let _ = client;
# Ok::<(), alpaca_data::Error>(())

Use credentials_from_env_names(...) when the surrounding runtime uses different variable names:

use alpaca_data::Client;

let client = Client::builder()
    .credentials_from_env_names("ALPACA_DATA_API_KEY", "ALPACA_DATA_SECRET_KEY")?
    .build()?;
# let _ = client;
# Ok::<(), alpaca_data::Error>(())

Environment helpers follow the same pairing rule:

• both variables present -> credentials are loaded onto the builder
• both variables absent -> the builder is left unchanged
• only one variable present -> Error::InvalidConfiguration

When both environment variables are present, ClientBuilder::build() applies the same credential validation and still rejects blank, whitespace-only, and HTTP header-invalid values before constructing the client.

Debug Redaction

ClientBuilder, Client, and resource clients redact configured credentials in Debug output.

If base_url(...) includes URL userinfo such as https://user:pass@example.test, Debug output removes that userinfo and shows only the sanitized URL.

Current Auth Rules

The current implementation requires credentials for:

• stocks
• options
• news
• corporate_actions

The currently implemented crypto HTTP endpoints can run without credentials.

This matches the current endpoint auth rules in the codebase and should be treated as an implementation fact, not a promise about future Alpaca policy changes.

Environment Variables Used By Live Tests

Repository live tests expect:

• APCA_API_KEY_ID
• APCA_API_SECRET_KEY
• ALPACA_LIVE_TESTS=1

Optional override:

• APCA_API_DATA_URL

Example:

export APCA_API_KEY_ID="your-key"
export APCA_API_SECRET_KEY="your-secret"
export ALPACA_LIVE_TESTS=1

Local .env Workflow

If your local .env stores credentials under names such as:

• ALPACA_DATA_API_KEY
• ALPACA_DATA_SECRET_KEY

Run the following exports before running live tests or examples:

export APCA_API_KEY_ID="$ALPACA_DATA_API_KEY"
export APCA_API_SECRET_KEY="$ALPACA_DATA_SECRET_KEY"

Base URL Override

The client defaults to:

https://data.alpaca.markets

Use base_url(...) only when you need a local test server or a different Alpaca-compatible endpoint.