This page lists every knob & switch exposed by the nekuda SDK and how to tweak them for production workloads.

​
Configuration Consistency 🎯

Important: Configure your NekudaClient once and reuse it throughout your application. Creating multiple clients with different configurations leads to confusion and bugs.
from nekuda import NekudaClient

# Configure once at startup, typically using environment variables
client = NekudaClient.from_env()
# Or explicitly:
# client = NekudaClient(api_key="sk_live_...", base_url="https://api.nekuda.ai")

# Use everywhere
user_id_alice = "alice_123"
user_alice = client.user(user_id_alice)

user_id_bob = "bob_456"
user_bob = client.user(user_id_bob)

​
Environment Variables

These are the primary way to configure the nekuda SDK.
VariableDescriptionDefault
NEKUDA_API_KEYRequired – Secret key identifying your nekuda account. Get this from the nekuda Dashboard.–
NEKUDA_BASE_URLOverride the API host. Defaults to production. Useful for pointing to staging or local mock servers.https://api.nekuda.ai
Both variables are consumed by NekudaClient.from_env().

​
Example .env file

.env
NEKUDA_API_KEY=sk_live_your_secret_key_here
# NEKUDA_BASE_URL=https://staging-api.nekuda.ai  # Uncomment for staging

​
Client Constructor Options

While environment variables are recommended, you can also configure the client directly. 
from nekuda import NekudaClient

client = NekudaClient(
    api_key: str, # Your NEKUDA_API_KEY
    base_url: str = "https://api.nekuda.ai",
    timeout: int = 30,
    *,
    max_retries: int = 3,
    backoff_factor: float = 0.5,
)
​
api_key
string
required
Your nekuda API key (starts with sk_live_ or sk_test_). This is mandatory.
​
base_url
string
default:"https://api.nekuda.ai"
API endpoint. The SDK automatically normalizes this (e.g., adds https://, removes trailing /). Only change this if you need to point to a non-production environment like staging.
​
timeout
int
default:"30"
Network timeout in seconds passed to the underlying httpx client.
​
max_retries
int
default:"3"
How many times to automatically retry on 5xx (server errors) or 429 (rate limit) responses.
​
backoff_factor
float
default:"0.5"
Exponential sleep multiplier between retries. sleep = (2 ** (retry_attempt - 1)) * backoff_factor.

​
URL Normalization 🎯

The SDK automatically normalizes the base_url. The default is https://api.nekuda.ai.

​
Configuration Examples

​
Configuration Patterns

This is the most flexible for different deployment environments (dev, staging, prod).
.env example
# For production
NEKUDA_API_KEY=sk_live_xxxxxxxxxxxx
NEKUDA_BASE_URL=https://api.nekuda.ai

# For staging
# NEKUDA_API_KEY=sk_test_yyyyyyyyyyyy
# NEKUDA_BASE_URL=https://staging-api.nekuda.ai
Python Code
from nekuda import NekudaClient
client = NekudaClient.from_env()

​
Pattern 2: Explicit Configuration

Useful if environment variables are not an option, or for quick local tests. 
from nekuda import NekudaClient
client = NekudaClient(
    api_key="sk_live_your_api_key",
    base_url="https://api.nekuda.ai",
    timeout=30
)

​
Pattern 3: Mixed Configuration (Overrides)

You can use from_env() and override specific parameters. 
from nekuda import NekudaClient
# Assumes NEKUDA_API_KEY and NEKUDA_BASE_URL are set in environment
client = NekudaClient.from_env(
    timeout=60,      # Override default timeout
    max_retries=5    # Override default retries
)

​
Global Default Client

For quick scripts or simple applications, you can register a single global client. 
from nekuda import NekudaClient, set_default_client, get_default_client

# Set once at startup, typically using environment configuration
set_default_client(NekudaClient.from_env())

# Use anywhere in your code without passing the client instance
def some_function():
    client = get_default_client()
    # user_id must still be provided to client.user()
    user_context = client.user("some_user_id")
    # ... use user_context.create_mandate(...)
Using a global client can make testing and managing configurations in larger applications more complex. Be mindful of where and how the client is configured. Never share secrets (API key) across process boundaries unless you understand the security implications.

​
Advanced Features (Built-in)

These features are enabled by default in the nekuda SDK.

​
Response Validation

The SDK automatically validates all API responses.

​
Type Safety

All methods return typed response models, enabling IDE autocompletion and static analysis. 
from nekuda import NekudaClient
client = NekudaClient.from_env()
user_context = client.user("test_user_123")
# Assume mandate_id is obtained
# reveal_response = user_context.request_card_reveal_token(mandate_id=...)
# print(reveal_response.reveal_token)  # Autocomplete works!
# print(reveal_response.expires_at)    # Optional[datetime]

​
Proxy Support

The SDK supports standard proxy environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY).
Example Proxy Configuration
export HTTP_PROXY=http://proxy.yourcompany.com:8080
export HTTPS_PROXY=http://proxy.yourcompany.com:8080
export NO_PROXY=localhost,127.0.0.1,internal.service
No special SDK configuration is needed for proxies if these environment variables are set before your script runs.

​
Logging & Debugging

Enable detailed logging from the SDK to troubleshoot issues. 
import logging

# To see all SDK debug messages, including request/response details:
logging.basicConfig(level=logging.DEBUG) # Set root logger to DEBUG
# Or more targeted:
# logging.getLogger("nekuda").setLevel(logging.DEBUG)

# Example output you might see:
# DEBUG:nekuda.client:Making POST request to https://api.nekuda.ai/v1/mandates with headers: ..., payload: ...
# DEBUG:nekuda.client:Received 201 response from https://api.nekuda.ai/v1/mandates with data: {"mandate_id": ...}

​
Configuration FAQ