Skip to main content

Anthropic Provider Guide

Direct access to Claude models with flexible authentication options

Overview​

Anthropic provides direct API access to Claude, one of the most capable AI model families available. NeuroLink supports both API key authentication for production deployments and OAuth authentication for Claude Pro/Max subscription users.

Claude Subscription Users

If you have a Claude Pro or Max subscription, you can use OAuth authentication to leverage your subscription quota directly. See OAuth Setup below.

Key Benefits​

  • Claude Sonnet 4: Latest balanced model with extended thinking support
  • Claude Opus 4: Latest flagship model for advanced reasoning
  • Claude 3.5 Sonnet: Proven balanced performance for most tasks
  • Extended Thinking: Deep reasoning mode on Sonnet 4 and Opus 4
  • 200K Context: All models support 200,000-token context windows
  • Multimodal: Vision capabilities for image analysis
  • Tool Use: Function calling for agent workflows

Authentication Options​

MethodBest ForBilling
API KeyProduction, server-side appsPay-per-token
OAuthPersonal dev with Pro/Max subscriptionSubscription quota

Quick Start​

1. Get Your API Key​

  1. Visit console.anthropic.com
  2. Sign in or create an account
  3. Navigate to API Keys section
  4. Click Create Key
  5. Copy your new API key (starts with sk-ant-)

2. Configure Environment​

Add to your .env file:

# Required: Your Anthropic API key
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# Optional: Override default model (defaults to claude-3-5-sonnet-20241022)
ANTHROPIC_MODEL=claude-sonnet-4-20250514

3. Test the Setup​

import { NeuroLink } from "@juspay/neurolink";

const ai = new NeuroLink();

const result = await ai.generate({
  input: { text: "Explain quantum computing in simple terms" },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
});

console.log(result.content);

Supported Models​

Available Models (from AnthropicModels enum)​

Enum KeyModel IDFamilyContextMax OutputVisionExtended ThinkingDeprecated
CLAUDE_OPUS_4_5claude-opus-4-5-20251101Opus----No
CLAUDE_SONNET_4_5claude-sonnet-4-5-20250929Sonnet----No
CLAUDE_4_5_HAIKUclaude-haiku-4-5-20251001Haiku----No
CLAUDE_OPUS_4_1claude-opus-4-1-20250805Opus----No
CLAUDE_OPUS_4_0claude-opus-4-20250514Opus200K64,000YesYesNo
CLAUDE_SONNET_4_0claude-sonnet-4-20250514Sonnet200K64,000YesYesNo
CLAUDE_SONNET_3_7claude-3-7-sonnet-20250219Sonnet----No
CLAUDE_3_5_SONNETclaude-3-5-sonnet-20241022Sonnet200K8,192YesNoNo
CLAUDE_3_5_HAIKUclaude-3-5-haiku-20241022Haiku200K8,192NoNoNo
CLAUDE_3_SONNETclaude-3-sonnet-20240229Sonnet----Yes
CLAUDE_3_OPUSclaude-3-opus-20240229Opus200K4,096YesNoYes
CLAUDE_3_HAIKUclaude-3-haiku-20240307Haiku200K4,096YesNoYes

The detailed capabilities (context window, max output, vision, etc.) are defined in MODEL_METADATA within src/lib/models/anthropicModels.ts for the models that have entries there: Claude 3 Haiku, Claude 3.5 Haiku, Claude 3.5 Sonnet, Claude 3.5 Sonnet V2, Claude Sonnet 4, Claude 3 Opus, and Claude Opus 4.

Default Model​

The default model when no model is specified is claude-3-5-sonnet-20241022 (set via AnthropicModels.CLAUDE_3_5_SONNET). This can be overridden with the ANTHROPIC_MODEL environment variable.

Model Selection by Use Case​

import { NeuroLink } from "@juspay/neurolink";

const ai = new NeuroLink();

// Fast, cost-effective responses
const quickResult = await ai.generate({
  input: { text: "Summarize this text..." },
  provider: "anthropic",
  model: "claude-3-5-haiku-20241022",
});

// Balanced performance (recommended default)
const balancedResult = await ai.generate({
  input: { text: "Analyze this code..." },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
});

// Latest Sonnet with extended thinking
const sonnet4Result = await ai.generate({
  input: { text: "Design a distributed caching system" },
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  thinkingLevel: "high",
});

// Latest flagship for advanced reasoning
const opusResult = await ai.generate({
  input: { text: "Solve this complex problem..." },
  provider: "anthropic",
  model: "claude-opus-4-20250514",
});

Claude Subscription Tiers​

Anthropic offers different access tiers, each with varying rate limits and model access:

TierAccess MethodModels AvailableBest For
Freeclaude.ai accountHaiku only (3 Haiku, 3.5 Haiku)Exploration, personal use
Pro ($20/month)OAuth + claude.aiHaiku + Sonnet (3.5 Sonnet, Sonnet 4)Professional use, higher volume
Max ($100/month)OAuth + claude.aiAll models (including Opus)Heavy use, all model access
Max 5xOAuth + claude.aiAll models5x usage multiplier
Max 20xOAuth + claude.aiAll models20x usage multiplier
APIAPI KeyAll modelsProduction, programmatic access

Model Access by Tier (MODEL_TIER_ACCESS)​

ModelFreeProMax / Max 5x / Max 20xAPI
claude-3-haiku-20240307YesYesYesYes
claude-3-5-haiku-20241022YesYesYesYes
claude-3-5-sonnet-20241022NoYesYesYes
claude-3-5-sonnet-v2-20241022NoYesYesYes
claude-sonnet-4-20250514NoYesYesYes
claude-3-opus-20240229NoNoYesYes
claude-opus-4-20250514NoNoYesYes

Default Models by Tier (DEFAULT_MODELS_BY_TIER)​

TierDefault Model
Freeclaude-3-5-haiku-20241022
Proclaude-sonnet-4-20250514
Maxclaude-opus-4-20250514
Max 5xclaude-opus-4-20250514
Max 20xclaude-opus-4-20250514
APIclaude-sonnet-4-20250514

Note: The global provider default (when no subscription tier is active) is claude-3-5-sonnet-20241022. The tier defaults above only apply when a subscription tier is configured. When a requested model is not available for the user's subscription tier, the provider automatically falls back to the recommended default model for that tier and logs a warning.

Authentication Methods​

The standard method using Anthropic API keys. Best for:

  • Production deployments
  • Server-side applications
  • Predictable billing (pay-per-token)
  • Full API control

Environment Variables​

# Required
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# Optional: Override default model
ANTHROPIC_MODEL=claude-sonnet-4-20250514

The provider reads the API key via ANTHROPIC_API_KEY. The key format is validated against the pattern sk-ant-*.

SDK Configuration​

import { NeuroLink } from "@juspay/neurolink";

const ai = new NeuroLink();

const result = await ai.generate({
  input: { text: "Analyze this code for bugs" },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
  temperature: 0.7,
  maxTokens: 2000,
});

Direct Provider Configuration​

The AnthropicProvider constructor accepts an optional AnthropicProviderConfig:

// Note: AnthropicProvider is not a top-level package export.
// Use relative imports within the codebase or access via the NeuroLink SDK.
import { AnthropicProvider } from "../src/lib/providers/anthropic.js";

const provider = new AnthropicProvider(
  "claude-sonnet-4-20250514", // modelName
  undefined, // sdk instance
  {
    authMethod: "api_key",
    apiKey: process.env.ANTHROPIC_API_KEY,
    enableBetaFeatures: true,
  },
);

OAuth Setup (Claude Pro/Max)​

OAuth authentication allows you to use your Claude Pro or Max subscription through NeuroLink, leveraging your subscription quota instead of API billing.

OAuth Limitations

OAuth authentication is designed for personal/development use. For production deployments, use API key authentication for better reliability and SLA guarantees.

CLI Authentication​

The auth command uses subcommands with the provider as a positional argument:

# Start interactive OAuth authentication (choose method)
pnpm run cli -- auth login anthropic

# Specify method directly
pnpm run cli -- auth login anthropic --method oauth

# Create API key via OAuth (recommended for Claude Pro/Max users)
pnpm run cli -- auth login anthropic --method create-api-key

# Traditional API key authentication
pnpm run cli -- auth login anthropic --method api-key

The login flow will:

  1. Open your default browser to https://claude.ai/oauth/authorize
  2. Prompt you to sign in to your Claude account
  3. Request authorization with scopes: user:profile, user:inference
  4. Exchange the authorization code for tokens using PKCE
  5. Store tokens securely in ~/.neurolink/anthropic-credentials.json

Token Management​

# Check authentication status
pnpm run cli -- auth status

# Check status for a specific provider
pnpm run cli -- auth status anthropic

# Refresh tokens manually
pnpm run cli -- auth refresh anthropic

# Clear credentials (logout)
pnpm run cli -- auth logout anthropic

Token Storage​

Tokens are stored at ~/.neurolink/anthropic-credentials.json with 0o600 file permissions (owner read/write only). The file format is:

{
  "type": "oauth",
  "oauth": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresAt": 1740000000000,
    "tokenType": "Bearer"
  },
  "provider": "anthropic",
  "updatedAt": 1739900000000
}

The expiresAt field is stored as Unix milliseconds (i.e., Date.now() scale).

The TokenStore class (used for multi-provider token storage) stores tokens at ~/.neurolink/tokens.json with XOR-based obfuscation.

Token Resolution Priority​

When the AnthropicProvider is initialized, it resolves OAuth tokens in this order:

  1. config.oauthToken (passed directly to the constructor)
  2. Stored credentials file at ~/.neurolink/anthropic-credentials.json
  3. Environment variables: ANTHROPIC_OAUTH_TOKEN or CLAUDE_OAUTH_TOKEN

Environment variable tokens can be either:

  • A plain access token string
  • A JSON object with accessToken, refreshToken, and expiresAt fields

Auto-Refresh Behavior​

Token refresh happens automatically on every generate() and stream() call. Before each API request, refreshAuthIfNeeded() is called, which:

  1. Checks if the token has expiry information
  2. If the token is expired or will expire within 5 minutes, attempts refresh
  3. Sends a refresh request to https://console.anthropic.com/v1/oauth/token using the Claude Code client ID
  4. Mutates the token object in-place so the fetch wrapper picks up the new access token automatically
  5. Persists the refreshed token to ~/.neurolink/anthropic-credentials.json on disk

If the token is expired and no refresh token is available, an AuthenticationError is thrown.

OAuth Environment Variables​

# Set an OAuth token directly (plain string or JSON)
ANTHROPIC_OAUTH_TOKEN=your-access-token-here

# Or use CLAUDE_OAUTH_TOKEN as an alternative
CLAUDE_OAUTH_TOKEN=your-access-token-here

# Set subscription tier explicitly (auto-detected if not set)
ANTHROPIC_SUBSCRIPTION_TIER=pro

OAuth SDK Configuration​

// Note: AnthropicProvider is not a top-level package export.
// Use relative imports within the codebase or access via the NeuroLink SDK.
import { AnthropicProvider } from "../src/lib/providers/anthropic.js";

const provider = new AnthropicProvider("claude-sonnet-4-20250514", undefined, {
  authMethod: "oauth",
  oauthToken: {
    accessToken: "your-access-token",
    refreshToken: "your-refresh-token",
    expiresAt: Date.now() + 3600 * 1000, // Unix milliseconds
    tokenType: "Bearer",
  },
  subscriptionTier: "pro",
  enableBetaFeatures: true,
});

Extended Thinking​

Claude Sonnet 4 and Claude Opus 4 support extended thinking, allowing the model to reason more deeply before responding.

Thinking Levels​

LevelDescriptionUse Case
minimalBasic reasoningQuick decisions
lowQuick reasoningSimple analysis
mediumBalanced thinkingCode review, moderate complexity
highDeep reasoningComplex proofs, architecture design

Configuration​

// Enable extended thinking
const result = await ai.generate({
  input: { text: "Design a distributed caching system" },
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  thinkingLevel: "high",
});

CLI Usage​

pnpm run cli -- generate "Solve this logic puzzle..." \
  --provider anthropic \
  --model "claude-sonnet-4-20250514" \
  --thinking-level high

Beta Features​

The Anthropic provider supports beta features via the anthropic-beta header. The following beta headers are included by default when enableBetaFeatures is true:

  • claude-code-20250219 -- Claude Code specific features
  • interleaved-thinking-2025-05-14 -- Interleaved thinking mode
  • fine-grained-tool-streaming-2025-05-14 -- Fine-grained tool streaming

These correspond to the AnthropicBetaFeature enum values in src/lib/constants/enums.ts:

enum AnthropicBetaFeature {
  CLAUDE_CODE = "claude-code-20250219",
  INTERLEAVED_THINKING = "interleaved-thinking-2025-05-14",
  FINE_GRAINED_STREAMING = "fine-grained-tool-streaming-2025-05-14",
}

For OAuth mode, the beta headers are different: oauth-2025-04-20 and interleaved-thinking-2025-05-14 are sent (the claude-code-20250219 header is only included if it was present in the original request headers, as it can trigger authorization errors with OAuth tokens).

Multimodal Capabilities​

Claude models with vision support can analyze images.

Image Analysis​

const result = await ai.generate({
  input: {
    text: "Describe what you see in this image",
    images: ["data:image/jpeg;base64,..."],
  },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
});
# From file path (CLI)
pnpm run cli -- generate "Describe this image" \
  --provider anthropic \
  --image ./photo.jpg

PDF Processing​

const result = await ai.generate({
  input: {
    text: "Summarize the key points in this document",
    pdfs: ["./document.pdf"],
  },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
});

Tool Use / Function Calling​

Claude supports tool use for building agent workflows. All models with supportsToolUse: true in MODEL_METADATA support this feature.

const tools = [
  {
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: { type: "string", description: "City name" },
      },
      required: ["location"],
    },
  },
];

const result = await ai.generate({
  input: { text: "What's the weather in Tokyo?" },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
  tools,
});

console.log(result.toolCalls);
OAuth Tool Name Prefixing

When using OAuth authentication, tool names are automatically prefixed with mcp_ in API requests and the prefix is stripped from responses. This is handled transparently by the OAuth fetch wrapper.

Streaming Responses​

const stream = await ai.stream({
  input: { text: "Write a detailed article about AI" },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022",
});

OAuth token refresh also happens automatically before stream() calls.

Rate Limit Handling​

The Anthropic provider tracks rate limit information from API response headers. The following headers are parsed after each request:

  • anthropic-ratelimit-requests-limit / anthropic-ratelimit-requests-remaining
  • anthropic-ratelimit-tokens-limit / anthropic-ratelimit-tokens-remaining
  • anthropic-ratelimit-requests-reset / anthropic-ratelimit-tokens-reset
  • retry-after (on 429 responses)

You can access this information programmatically:

const provider = new AnthropicProvider();

// After making a request...
const metadata = provider.getLastResponseMetadata();
console.log(metadata?.rateLimit?.requestsRemaining);
console.log(metadata?.rateLimit?.tokensRemaining);

// Usage tracking
const usage = provider.getUsageInfo();
if (usage) {
  console.log("Requests made:", usage.requestCount);
  console.log("Message quota used:", usage.messageQuotaPercent + "%");
  console.log("Token quota used:", usage.tokenQuotaPercent + "%");
  console.log("Rate limited:", usage.isRateLimited);
}

Warnings are logged automatically when:

  • Remaining requests drops to 5 or fewer
  • Remaining tokens drops below 10% of the limit

Configuration Reference​

Environment Variables​

VariableDescriptionDefaultRequired
ANTHROPIC_API_KEYAPI key for authentication-Yes*
ANTHROPIC_MODELDefault model to useclaude-3-5-sonnet-20241022No
ANTHROPIC_SUBSCRIPTION_TIERSubscription tier: free, pro, max, max_5, max_20, apiAuto-detectedNo
ANTHROPIC_OAUTH_TOKENOAuth token (plain access token string, or JSON {"accessToken":"...","refreshToken":"...","expiresAt":...})-No**
CLAUDE_OAUTH_TOKENAlternative OAuth token env var (same format as above)-No**

*Required for API key authentication. Not required when using OAuth. **Used when authMethod is oauth and no stored credentials file exists. The expiresAt field uses Unix milliseconds (Date.now() scale).

AnthropicProviderConfig Interface​

interface AnthropicProviderConfig {
  /** Auth method: "api_key" or "oauth". Auto-detected if not set. */
  authMethod?: AnthropicAuthMethod;

  /** Subscription tier. Auto-detected from environment or "api" for API key auth. */
  subscriptionTier?: ClaudeSubscriptionTier;

  /** Whether to enable beta features. Defaults to true. */
  enableBetaFeatures?: boolean;

  /** OAuth token for OAuth authentication. */
  oauthToken?: OAuthToken;

  /** API key for API key authentication. Read from env if not provided. */
  apiKey?: string;
}

CLI Provider Options​

The --provider flag accepts anthropic (or anthropic-subscription, which is automatically mapped to anthropic with subscription mode enabled). Additional flags for subscription features:

FlagValuesDescription
--provider / -panthropicUse Anthropic provider
--auth-methodapi-key, oauthAuthentication method
--subscription-tierfree, pro, max, max_5, max_20, apiSubscription tier
--enable-beta(boolean)Enable beta features
--model / -mmodel ID stringSpecific model to use

Example:

pnpm run cli -- generate "Hello" \
  --provider anthropic \
  --auth-method oauth \
  --subscription-tier pro

Error Handling​

The Anthropic provider maps errors to specific error types:

Error TypeCondition
AuthenticationErrorInvalid API key, expired OAuth token, failed token refresh
RateLimitErrorRate limit exceeded (429 responses)
NetworkErrorConnection failures, timeouts
ProviderErrorServer errors (5xx), other provider-side failures

Common Issues​

"Invalid API key"​

# Verify key format (should start with sk-ant-)
echo $ANTHROPIC_API_KEY | head -c 20
# Expected: sk-ant-api03-xxxx...

# Get new key at https://console.anthropic.com

"OAuth token expired"​

OAuth tokens are auto-refreshed before each request. If refresh fails:

# Refresh manually
pnpm run cli -- auth refresh anthropic

# Or re-authenticate
pnpm run cli -- auth login anthropic

"Model access denied" / Model unavailable for tier​

When a model is not available for your subscription tier, the provider automatically falls back to the recommended model for your tier. To use a specific model, ensure your tier supports it (see Model Access by Tier).

// Check model access programmatically
const provider = new AnthropicProvider();
if (provider.validateModelAccess("claude-opus-4-20250514")) {
  // Model is accessible
} else {
  // Falls back to tier default
}

"Rate limit exceeded" (429)​

  1. For Free tier: Upgrade to Pro or Max
  2. For API: Request a rate limit increase
  3. Check provider.getUsageInfo() for current quota usage

Helper Functions​

The src/lib/models/anthropicModels.ts module exports utility functions for working with models and tiers:

import {
  isModelAvailableForTier,
  getRecommendedModelForTier, // alias for getDefaultModelForTier
  getModelCapabilities, // alias for getModelMetadata
  getAvailableModelsForTier,
  getMinimumTierForModel,
  getModelsWithCapability,
  getModelsByFamily,
  getLatestModelsByFamily,
  validateModelAccess,
  compareTiers,
  ModelAccessError,
} from "@juspay/neurolink";

// Check if a model is available for a tier
isModelAvailableForTier("claude-opus-4-20250514", "pro"); // false
isModelAvailableForTier("claude-opus-4-20250514", "max"); // true

// Get the minimum tier required
getMinimumTierForModel("claude-opus-4-20250514"); // "max"

// Get all models with extended thinking
getModelsWithCapability("supportsExtendedThinking");
// ["claude-sonnet-4-20250514", "claude-opus-4-20250514"]

// Get latest non-deprecated model per family
getLatestModelsByFamily();
// { haiku: "claude-3-5-haiku-20241022", sonnet: "claude-sonnet-4-20250514", opus: "claude-opus-4-20250514" }

Best Practices​

Security​

  • Never commit API keys to version control
  • Use environment variables or secrets management
  • Rotate API keys periodically
  • OAuth tokens are stored with 0o600 permissions (owner read/write only)
# Use .env file (not committed to git)
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

# Add to .gitignore
echo ".env" >> .gitignore

Rate Limiting​

The provider tracks rate limits automatically and logs warnings when approaching limits. Monitor usage via getUsageInfo() and getLastResponseMetadata().

Additional Resources​