Docs home

Quickstart

This guide covers SDK installation, first-agent registration, and your first gated invoke call. Estimated time: 20 to 30 minutes.

Prerequisites

  • A Scalekix account (sign up free)
  • Python 3.9+ or Node.js 18+
  • A Scalekix API key from dashboard account settings

Step 1: Add the SDK

Install the Scalekix SDK using PyPI or npm:

Python 
pip install scalekix
Node.js 
npm install @scalekix/sdk

Step 2: Set up your API key

The SDK loads your Scalekix API key from the SKX_API_KEY environment variable. Define it in your shell or .env file:

Shell 
export SKX_API_KEY="skx_live_your_api_key_here"

Alternatively, provide the key to the client constructor directly if secrets are managed through a different mechanism:

Python 
import scalekix

client = scalekix.Client(api_key="skx_live_your_api_key_here")

Step 3: Add an agent

Call the register() method to create a credential for your agent. Specify the agent name, permitted scopes, and credential lifetime during registration. This runs once during deployment, rather than at runtime.

Python 
import scalekix

agent = scalekix.register(
    name="my-first-agent",
    scopes=["db:read", "api:call"],
    ttl_hours=720,
    tags={"env": "development"}
)

# Store the agent object. The SDK handles
# credential refresh automatically.
print(agent.id)   # skx://agent/my-first-agent/...
print(agent.name) # "my-first-agent"
Tip: Register each agent once in your deployment pipeline. Do not run register() whenever a process starts. If the name matches an agent already registered in your account, the SDK returns that existing agent.

Step 4: Send a gated invoke call

Route direct API calls through agent.invoke(). The Scalekix gateway validates the credential, enforces the scope, and forwards the request. Each call also generates a structured audit event.

Python 
response = agent.invoke(
    target="https://your-api.example.com/data",
    method="GET",
    headers={"Accept": "application/json"}
)

print(response.status_code)
print(response.json())

When an agent requests an action beyond its declared scopes, the gateway responds with 403 and records the denied request:

Python 
try:
    response = agent.invoke(
        target="https://your-api.example.com/data",
        method="DELETE"
    )
except scalekix.ScopeViolationError as e:
    print(e)
    # ScopeViolationError: agent 'my-first-agent'
    # attempted scope 'api:delete', not in
    # declared scopes ['db:read', 'api:call']

Step 5: Open the audit log

Each invoke() call creates a log event in your dashboard at Agents → [agent name] → Activity. Events are also available through the API:

Shell (cURL) 
curl -H "Authorization: Bearer $SKX_API_KEY" \
  "https://api.scalekix.com/v1/audit?agent_name=my-first-agent&limit=10"

Next steps