Documentation

Authentication

Authenticate your API requests using API keys. All requests must include a valid API key.

Getting Your API Key

Sign in to Guardy

Go to tryguardy.com.

Go to Settings → API Keys

Navigate to your organization settings.

Create a new API key

Click "Create API Key", name it, and copy the key immediately.

Using API Keys

HTTP Header (Recommended)

Include your API key in the Authorization header:

Authorization: Bearer guardy_live_xxxxxxxxxxxxx

cURL Example

curl -X POST https://api.tryguardy.com/api/sdk/sessions \
  -H "Authorization: Bearer guardy_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Session", "agentName": "test-agent", "userId": "user_123"}'

Python SDK

import guardy

# Option 1: Configure globally
guardy.configure(api_key="guardy_live_xxxxxxxxxxxxx")

# Option 2: Create client directly
from guardy import GuardyClient
client = GuardyClient(api_key="guardy_live_xxxxxxxxxxxxx")

# Option 3: Use environment variable (recommended)
# Set GUARDY_API_KEY in your environment
client = GuardyClient()  # Auto-reads from env

TypeScript SDK

import { GuardyClient } from '@guardy/sdk';

const client = new GuardyClient({
  apiKey: process.env.GUARDY_API_KEY
});

API Key Format

Guardy API keys follow this format:

guardy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

guardy_ — prefix identifying Guardy keys
live_ — environment (live for production)
Random string — unique identifier

Error Responses

401 Unauthorized

Missing or invalid API key.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

API key doesn't have permission for this action.

{
  "error": "Forbidden",
  "message": "API key does not have access to this resource"
}

Security Best Practices

Use environment variables — Store API keys in env vars, not in code
Never commit keys — Add .env to .gitignore and use secrets managers in CI/CD
Rotate keys regularly — Create new keys periodically and revoke old ones
Use separate keys per environment — Different keys for dev, staging, and production
Revoke compromised keys immediately — If a key is exposed, delete it in Settings right away

Next Steps

Sessions API

Create and manage sessions.

Events API

Track events within sessions.