API Reference

Python SDK

The official Python client for the XtraSecurity API. Built with native caching, type hints, and Zero-Trust injection.

Installation

>_Terminal

pip install xtrasecurity-sdk

Configuration

The SDK provides a primary wrapper class, XtraClient. It accepts an XtraClientOptions object during instantiation.

>_Terminal

from xtrasecurity import XtraClient, XtraClientOptions
 
# Initialize the client
# It will automatically use os.environ.get('XTRA_TOKEN') if available
client = XtraClient(XtraClientOptions(
    project_id="prj_123456789",
    cache_ttl=60 # Cache secrets in-memory for 60 seconds
))

Option	Type	Default	Description
token	`str`	`os.environ['XTRA_TOKEN']`	The API Token used for authentication.
project_id	`str`	`os.environ['XTRA_PROJECT_ID']`	The default project ID for all secret operations.
api_url	`str`	`https://www.xtrasecurity.in/api`	Override the base URL for self-hosted Enterprise instances.
cache	`bool`	`True`	Enables in-memory caching to prevent rate-limiting.
cache_ttl	`int`	`30`	Time-to-live for cached secrets in seconds.

Core Methods

get_secrets()

Fetches all secrets for a specific environment and branch, returning a standard dictionary. This method automatically utilizes the in-memory cache if enabled.

>_Terminal

# Fetch from production (main branch)
secrets = client.get_secrets("production")
print(secrets.get("DATABASE_URL"))
 
# Fetch from a specific branch and bypass cache
preview_secrets = client.get_secrets(
    env="staging", 
    branch="feature/new-ui", 
    no_cache=True
)

Parameter	Type	Description
env	`str`	Required. The target environment (e.g. 'production').
project_id	`str`	Optional override for the default project_id.
branch	`str`	Optional. Target a specific environment branch (defaults to 'main').
no_cache	`bool`	Optional. If True, forces a network request bypassing the in-memory cache.

inject_secrets()

A convenience method that fetches secrets and immediately populates os.environ. This is the recommended approach for standard Python web applications like Flask or Django.

>_Terminal

from xtrasecurity import XtraClient
import os
 
client = XtraClient()
 
# Instantly inject secrets into os.environ
client.inject_secrets("production", project_id="prj_123456789", branch="feature/new-ui", override=True)
 
# Now you can use them normally across your application
print(os.environ.get("DATABASE_URL"))

clear_cache()

Manually flushes the in-memory secret cache.

>_Terminal

client.clear_cache()

Advanced API Access

For power users building custom internal tools, XtraClient exposes the raw auto-generated service classes.

>_Terminal

from xtrasecurity import XtraClient
from xtrasecurity.exceptions import XtraError
 
client = XtraClient()
 
try:
    # Access the raw auto-generated API classes for advanced management
    project_info = client.projects.get_project("prj_123456789")
    
    # Create an environment branch programmatically
    client.branches.create_branch("prj_123456789", name="hotfix/api-v2", base_env="production")
    
except XtraError as e:
    print(f"XtraSecurity Error: {e.message}")

Error Handling

All internal SDK errors are thrown as instances of the XtraError exception class.