Authentication and Client Configuration

Purpose and Scope

This page explains how authentication and client configuration fit together in the official Anthropic TypeScript SDK. The main path is intentionally simple: import the default Anthropic client, construct it with an API key, and call a resource such as messages. The README shows that the API key may be passed explicitly and that the environment variable ANTHROPIC_API_KEY is the default, so ordinary server-side applications can avoid hardcoding secrets in source. The same page also frames the package as a server-side TypeScript and JavaScript SDK for the Claude API, which matters because secret-bearing client construction is designed around trusted runtimes rather than public browser bundles.

Sources: README.md, src/index.ts

The configuration surface is broader than the first request example. The client type and option type are exported from the package entrypoint, which lets applications centralize client creation in their own dependency-injection or configuration layer. In practice, that means production services usually build one configured client from environment variables or deployment secrets, while tests can pass an explicit key, base URL, headers, or other request-level overrides. The source evidence also shows credential-profile tests for local configuration files, making this page relevant both to direct API-key usage and to CLI or profile-driven workflows that share SDK credential helpers.

Sources: src/index.ts, src/client.ts, tests/credentials.test.ts

Relevant Source Files

• README.md - Shows the public installation and getting-started example, including the default ANTHROPIC_API_KEY behavior and the browser credential warning.
• src/client.ts - Defines the core Anthropic client, BaseAnthropic, ClientOptions, and request construction behavior used by the package entrypoint.
• src/index.ts - Re-exports the default Anthropic client, named client classes, ClientOptions, APIRequest, errors, middleware types, upload helpers, and other public SDK entrypoints.
• tests/credentials.test.ts - Exercises configuration and credential profile loading, environment variable precedence, platform detection, and profile file lookup behavior.
• tests/buildHeaders.test.ts - Documents header merging semantics, nullable header removal, cookie joining, and append behavior for helper headers.

Core Authentication Model

The primary authentication model for the standard SDK is an Anthropic API key supplied to the Anthropic constructor or read from ANTHROPIC_API_KEY. The README example passes process environment state into the constructor and notes that doing so is the default and can be omitted. That convention lets server processes rely on their deployment platform for secret injection while keeping application code portable. Official Claude documentation also distinguishes ordinary API keys from Admin API keys used for organization administration; when building with this SDK, choose the credential type that matches the API family you are calling rather than treating every token as interchangeable.

Sources: README.md

Browser handling is a security-sensitive part of the configuration story. The README states that web browser support is disabled by default to avoid exposing secret API credentials, and that browser use requires explicitly setting dangerouslyAllowBrowser to true. That option name is intentionally forceful because a bundled API key can be extracted by users of the application. For web apps, prefer a server route, edge function, or backend service that holds the key and calls Claude on behalf of the browser. Only enable direct browser access for controlled experiments or environments where credential exposure is acceptable.

Sources: README.md, src/client.ts

Client Options and Environment Variables

The public package entrypoint exports Anthropic as both the default client and a named export, along with BaseAnthropic and ClientOptions. It also exports APIRequest, middleware types, upload helpers, pagination promises, parser types, and the SDK error hierarchy. For configuration, the important practical consequence is that the package has a stable central import surface: application code can import the client and its option type from the package root, then keep all authentication, timeout, base URL, header, and middleware decisions in one factory function. That factory becomes the right place to separate local development defaults from production secrets.

Sources: src/index.ts, src/client.ts

Credential-profile behavior is covered by tests rather than by the quickstart snippet. The credential tests preserve and restore environment variables including ANTHROPIC_BASE_URL, ANTHROPIC_CONFIG_DIR, ANTHROPIC_PROFILE, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_SCOPE, ANTHROPIC_SERVICE_ACCOUNT_ID, APPDATA, HOME, and XDG_CONFIG_HOME. The tests create temporary config directories and verify that loading returns null when a profile does not exist, loads a default profile, follows an active_config pointer, and allows an explicit profile argument to override both ANTHROPIC_PROFILE and active_config. That precedence matters when diagnosing surprising local authentication behavior.

Sources: tests/credentials.test.ts

Configuration Patterns

For most applications, the recommended pattern is a small module that constructs exactly one SDK client from deployment configuration. In local development, ANTHROPIC_API_KEY can be set in a shell, process manager, or secret file loaded before the process starts. In production, inject the same variable through the hosting platform secret manager. If a service needs to target a proxy, test double, or alternate endpoint, keep that decision near the same factory rather than scattering request options through business logic. This keeps authentication auditable and makes it easier to rotate keys without changing call sites.

Sources: README.md, src/client.ts

import Anthropic from '@anthropic-ai/sdk';
 
export function createClaudeClient() {
  return new Anthropic({
    apiKey: process.env['ANTHROPIC_API_KEY'],
  });
}

The profile-loading tests are useful for developer tooling, automation, and advanced deployments that rely on named local configuration rather than a single process environment variable. The tests show a default profile path, an active profile pointer, and an explicit argument that wins over both the environment-selected profile and the active_config file. When documenting or supporting a team setup, be explicit about which profile is expected and whether ANTHROPIC_CONFIG_DIR is set. Otherwise, a developer may be reading one file while the SDK is resolving another profile selected by environment or active configuration state.

Sources: tests/credentials.test.ts

Header Construction and Request Customization

Authentication configuration often travels with headers, so the header-building tests are part of the practical contract. The tests show that header names are normalized case-insensitively, undefined values do not remove an earlier value, and null records an intentional removal. Cookies receive special treatment: arrays and repeated cookie entries are joined with semicolons, while ordinary repeated array headers are joined with commas. The x-stainless-helper header is append-oriented and de-duplicates repeated helper values, but a null value can still clear it. These rules are important when combining SDK defaults, middleware, and per-request overrides.

Sources: tests/buildHeaders.test.ts

The most common header-related mistake is trying to override a default by setting an option to undefined. According to the tests, undefined is ignored in a merge and the earlier value remains. Use null when the intent is to suppress a header, and use a concrete string when the intent is to replace a header. This is especially relevant around custom middleware, proxy authentication, diagnostics, and beta or helper headers. Treat header configuration as layered: client defaults first, middleware or helper additions next, and request-specific overrides last, with null reserved for deliberate deletion.

Sources: tests/buildHeaders.test.ts, src/client.ts

API Reference

Sources: src/index.ts, src/client.ts

Testing Signals and Next Steps

Use the tests as behavioral documentation when validating configuration changes. A change to credential loading should preserve profile precedence, temporary config directory behavior, and environment restoration assumptions shown in tests/credentials.test.ts. A change to request customization should preserve the merge semantics in tests/buildHeaders.test.ts, especially the difference between null and undefined and the special joining rules for cookies and helper headers. For implementation work, start from the README usage, confirm the public exports in src/index.ts, and then inspect src/client.ts before changing constructor defaults or request assembly.

Sources: README.md, src/index.ts, src/client.ts, tests/credentials.test.ts, tests/buildHeaders.test.ts

Related pages to read next: Quickstart: Messages for the first authenticated call, Anthropic Client Reference for constructor-level API details, Request Options, Errors, and Retries for per-request behavior, and Admin API for organization-level API-key management concepts.