API Keys
API keys authenticate your requests to create attestations. This guide covers how to get keys, manage them securely, and handle common scenarios.
Getting Your First Key
Step 1: Request a Verification Code
curl -X POST https://api.treeship.dev/v1/keys/request \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com"}'
{
"message": "Verification code sent to you@example.com",
"expires_in": 600
}
Step 2: Verify and Get Your Key
curl -X POST https://api.treeship.dev/v1/keys/verify \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "code": "123456"}'
{
"api_key": "ts_live_a1b2c3d4e5f6...",
"key_id": "key_abc123",
"created_at": "2026-02-23T10:00:00Z"
}
Save this key immediately! It’s only shown once. If you lose it, you’ll need to generate a new one.
Using Your Key
Environment Variable (Recommended)
export TREESHIP_API_KEY=ts_live_a1b2c3d4e5f6...
Python SDK
from treeship_sdk import Treeship
# From environment (recommended)
ts = Treeship()
# Or explicit
ts = Treeship(api_key="ts_live_...")
CLI
# From environment
export TREESHIP_API_KEY=ts_live_...
treeship attest --action "..." --inputs-hash "..."
# Or configure once
treeship config set api-key ts_live_...
Direct API
curl -X POST https://api.treeship.dev/v1/attest \
-H "Authorization: Bearer ts_live_..." \
-H "Content-Type: application/json" \
-d '{"agent_slug": "my-agent", "action": "...", "inputs_hash": "..."}'
Managing Keys
Check Key Status
curl https://api.treeship.dev/v1/keys/info \
-H "Authorization: Bearer $TREESHIP_API_KEY"
{
"key_id": "key_abc123",
"email": "you@example.com",
"created_at": "2026-02-23T10:00:00Z",
"attestations_today": 42,
"rate_limit": 1000
}
Revoke a Key
If a key is compromised or no longer needed:
curl -X DELETE https://api.treeship.dev/v1/keys \
-H "Authorization: Bearer $TREESHIP_API_KEY"
Rate Limits
| Limit | Value |
|---|
| Attestations per day | 1,000 |
| Attestations per minute | 100 |
- Response:
429 Too Many Requests
- Header:
Retry-After: <seconds>
Need higher limits? Contact us at hello@treeship.dev.
Best Practices
Use Environment Variables
Never hardcode keys in source code.
Use Different Keys Per Environment
Separate keys for dev, staging, prod.
Rotate Keys Regularly
Generate new keys periodically.
Monitor Usage
Check /keys/info to track attestation counts.
Don’t
Commit Keys to Git
Add .env to .gitignore.
Share Keys Across Services
Each service should have its own key.
Log Full Keys
Log only key prefixes: ts_live_a1b2....
Ignore Revocation
Revoke keys immediately if compromised.
ts_live_<32 bytes base64>
ts_ - Treeship identifierlive_ - Environment (live = production)- Remaining: 256 bits of cryptographically random data
This format makes keys:
- Easy to identify in logs and code
- Hard to accidentally expose (distinct prefix)
- Impossible to guess (256-bit entropy)
Multiple Keys
You can have multiple active keys. Common patterns:
| Pattern | Keys |
|---|
| Per environment | dev-key, staging-key, prod-key |
| Per service | agent-a-key, agent-b-key |
| Per team member | Individual keys for testing |
