Docs/Agent SDK Authentication

Agent SDK Authentication

Give your AI agent a SatGate token programmatically — Python, Node, or raw HTTP.

Overview

Every agent that connects through SatGate needs a capability token (a macaroon). You can mint tokens in the dashboard, but for production you want your agent to authenticate programmatically — at startup, on deploy, or on-demand.

Three options, from simplest to most flexible:

  1. Environment variable — paste a pre-minted token into your agent's config
  2. SDK — use the Python or Node SDK to validate, delegate, and manage tokens
  3. Mint + Identity Provider — auto-issue tokens based on workload identity (separate guide)

Option 1: Environment variable

The simplest path. Mint a token in the Connect Agent flow, then pass it as an environment variable.

bash
# .env or your deploy config
SATGATE_TOKEN="v2:your-macaroon-token-here"
SATGATE_URL="https://mcp.your-tenant.satgate.io"

Your MCP client (Cursor, Claude Code, custom) reads these at startup. No SDK needed.

Option 2: Python SDK

bash
pip install satgate

Authenticate and call tools

python
from satgate import SatGateClient

# Initialize with your token
client = SatGateClient(
    url="https://mcp.your-tenant.satgate.io",
    token="v2:your-macaroon-token-here"
)

# Validate token (check budget remaining, caveats, etc.)
info = client.validate()
print(f"Tenant: {info.tenant_id}")
print(f"Budget remaining: {info.budget_remaining} credits")

# List available tools
tools = client.tools()
for tool in tools:
    print(f"  {tool.name} ({tool.upstream})")

# Call a tool
result = client.call_tool("calculator", {"expression": "42 * 17"})
print(result)

Delegate a sub-token

Create a scoped token for a sub-agent with a tighter budget — no server roundtrip needed.

python
# Delegate: create a child token with 100-credit budget
child_token = client.delegate(
    budget_credits=100,
    label="research-agent",
    expires_in="24h"
)

# Give the child token to your sub-agent
sub_agent = spawn_agent(token=child_token)

# The parent token's budget is NOT affected until
# the child actually spends credits

LangChain integration

python
from satgate.langchain import SatGateToolkit
from langchain.agents import initialize_agent

# Wrap SatGate tools as LangChain tools
toolkit = SatGateToolkit(
    url="https://mcp.your-tenant.satgate.io",
    token="v2:your-token"
)

agent = initialize_agent(
    tools=toolkit.get_tools(),
    llm=llm,
    agent="zero-shot-react-description"
)

Option 3: Node SDK

bash
npm install @satgate/sdk

Authenticate and call tools

typescript
import { SatGateClient } from '@satgate/sdk';

const client = new SatGateClient({
  url: 'https://mcp.your-tenant.satgate.io',
  token: 'v2:your-macaroon-token-here',
});

// Validate token
const info = await client.validate();
console.log(`Budget: ${info.budgetRemaining} credits`);

// List tools
const tools = await client.tools();
tools.forEach(t => console.log(`  ${t.name}`));

// Call a tool
const result = await client.callTool('echo', { message: 'hello' });
console.log(result);

Delegate a sub-token

typescript
// Create a child token — runs locally, no API call
const childToken = client.delegate({
  budgetCredits: 100,
  label: 'data-pipeline-agent',
  expiresIn: '1h',
});

// Pass to sub-agent
const subAgent = new SubAgent({ token: childToken });

Option 4: Raw HTTP

No SDK? Use the admin API directly.

Validate a token

bash
curl -X POST https://mcp.your-tenant.satgate.io/api/v1/validate \
  -H "Authorization: Bearer v2:your-token" \
  -H "Content-Type: application/json"

# Response:
# {
#   "valid": true,
#   "tenant_id": "b605e0f0-...",
#   "budget_remaining": 450,
#   "caveats": ["tenant_id = b605e0f0-..."],
#   "expires_at": "2026-03-01T00:00:00Z"
# }

Mint a token (admin)

bash
curl -X POST https://mcp.your-tenant.satgate.io/api/v1/mint \
  -H "Authorization: Bearer v2:admin-root-token" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "deploy-agent",
    "budget_credits": 500,
    "caveats": ["tenant_id = your-tenant-id"],
    "expires_in": "30d"
  }'

# Response:
# {
#   "token": "v2:newly-minted-macaroon...",
#   "signature": "a1b2c3..."
# }

Best practices

  • Never hardcode tokens in source. Use environment variables, secrets managers (Vault, AWS Secrets Manager, 1Password), or the Mint identity flow.
  • Delegate, don't share. Each agent should have its own token. Use delegation to create child tokens with scoped budgets — the parent budget isn't touched until the child spends.
  • Set expiration. Tokens should expire. 24h for ephemeral agents, 30d for long-running services. Expired tokens fail cleanly.
  • Start with Observe. Mint a 0-credit token (or omit budget) to run in Observe mode. You get full monitoring with zero risk of blocking your agent.
  • Rotate tokens on deploy. Treat tokens like passwords. Mint fresh on each deploy, revoke old ones.

Related