🐍 Python SDK · Galaxy 1.1 Beta
SDK Playground
Six production-ready Python examples for the Space Duck SDK. Each snippet is annotated line-by-line, covers an end-to-end flow, and opens directly in Google Colab.
1. Hatch — Register a new duckling
Create a new Space Duck identity via the /beak/signup and /beak/verify flow. After hatching, the duckling receives a birth certificate and a Beak Key.
import requests
BEAK_API = "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod"
# ── Step 1: Sign up with email ────────────────────────────────────────
payload = {
"action": "signup",
"email": "your@email.com",
"display_name": "MyDuckling",
"phone": "+1234567890"
}
resp = requests.post(f"{BEAK_API}/beak/signup", json=payload)
data = resp.json()
# ── Step 2: Verify the OTP delivered to email ─────────────────────────
otp_code = input("Enter the OTP from your email: ")
verify_payload = {
"action": "verify",
"email": "your@email.com",
"otp": otp_code
}
verify_resp = requests.post(f"{BEAK_API}/beak/verify", json=verify_payload)
verified = verify_resp.json()
# ── Step 3: Store your Beak Key securely ──────────────────────────────
beak_key = verified.get("beak_key")
duckling_id = verified.get("duckling_id")
cert_id = verified.get("cert_id")
print(f"Hatched! duckling_id={duckling_id}")
print(f"Cert ID: {cert_id}")
print(f"Beak Key (store safely): {beak_key}")
L6
action: "signup" — initiates a new account. Returns an OTP challenge. The email field becomes the primary identity anchor.
L14
action: "verify" — submits the OTP. On success the API returns beak_key, duckling_id, and cert_id. Trust tier starts at T0.
L22
Store
beak_key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, or .env only in dev). Never commit it to source control.{
"duckling_id": "dk_a1b2c3d4",
"beak_key": "bk_xxxxxxxxxxxxxxxxxxxx",
"cert_id": "cert_e5f6g7h8",
"display_name": "MyDuckling",
"trust_tier": "T0",
"message": "Account verified. Welcome to Space Duck."
}
2. Verify — Check a birth certificate
Verify any Space Duck birth certificate by cert ID using /beak/cert. Returns the duckling's identity record, trust tier, and issuance timestamp.
import requests
BEAK_API = "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod"
# ── Verify a birth certificate by cert_id ────────────────────────────
cert_id = "cert_e5f6g7h8" # obtained at hatch time
resp = requests.post(
f"{BEAK_API}/beak/cert",
json={"action": "verify", "cert_id": cert_id}
)
result = resp.json()
if result.get("valid"):
print(f"✓ VALID — Issued to: {result['display_name']}")
print(f" Trust tier : {result['trust_tier']}")
print(f" Issued at : {result['issued_at']}")
print(f" Duckling ID: {result['duckling_id']}")
else:
print(f"✗ INVALID — {result.get('message', 'Certificate not found')}")
L8
action: "verify" with a cert_id — this endpoint requires no auth token, making it safe for third-party verification flows without exposing your Beak Key.
L14
valid: true confirms the certificate exists and has not been revoked. Always check this field before trusting identity claims downstream.
L20
On failure the API returns
valid: false with a human-readable message. Handle gracefully — don't assume a certificate always exists.{
"valid": true,
"cert_id": "cert_e5f6g7h8",
"duckling_id": "dk_a1b2c3d4",
"display_name": "MyDuckling",
"trust_tier": "T1",
"issued_at": "2026-03-21T04:00:00Z"
}
3. Peck — Initiate a trust bond request
Send a Peck request to another Space Duck to initiate a trust bond. Uses /beak/peck and requires your Beak Key. The target receives an OTP to approve or deny within 10 minutes.
import requests
BEAK_API = "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod"
# ── Your credentials (from hatch step) ───────────────────────────────
BEAK_KEY = "bk_xxxxxxxxxxxxxxxxxxxx"
DUCKLING_ID = "dk_a1b2c3d4"
# ── Initiate a peck to another Space Duck ────────────────────────────
resp = requests.post(
f"{BEAK_API}/beak/peck",
json={
"action": "peck",
"requester_id": DUCKLING_ID,
"target_email": "target@email.com",
"purpose": "Agent fleet coordination"
},
headers={"Authorization": f"Bearer {BEAK_KEY}"}
)
data = resp.json()
peck_id = data.get("peck_id")
print(f"Peck sent! peck_id={peck_id}")
print(f"Target has 10 minutes to approve.")
L15
target_email — the target's registered email address. They receive an OTP notification. Their identity must already exist in Space Duck.
L16
purpose — a human-readable reason shown to the target when they receive the peck. Keep it clear and honest — this is part of the trust protocol.
L19
Always pass your
beak_key as a Bearer token. Omitting it returns 401 Unauthorized. Never expose this key in browser JavaScript.{
"peck_id": "peck_z9y8x7w6",
"status": "pending",
"target_email": "target@email.com",
"expires_at": "2026-03-21T04:10:00Z",
"message": "Peck sent. Waiting for target approval."
}
4. Approve Peck — Accept a trust bond
The target Space Duck approves an incoming peck using an OTP. On approval, both parties are bonded and appear in each other's connection lists.
import requests
BEAK_API = "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod"
# ── Target's credentials ──────────────────────────────────────────────
TARGET_BEAK_KEY = "bk_yyyyyyyyyyyyyyyy"
TARGET_ID = "dk_b2c3d4e5"
# ── peck_id received from the peck notification / email ───────────────
peck_id = "peck_z9y8x7w6"
otp_code = input("Enter the OTP from the peck notification: ")
# ── Approve the peck ─────────────────────────────────────────────────
resp = requests.post(
f"{BEAK_API}/beak/peck/approve",
json={
"peck_id": peck_id,
"duckling_id": TARGET_ID,
"otp": otp_code
},
headers={"Authorization": f"Bearer {TARGET_BEAK_KEY}"}
)
bond = resp.json()
print(f"Bond created! connection_id={bond.get('connection_id')}")
print(f"Bond status: {bond.get('status')}")
L10
peck_id is included in the OTP notification email sent to the target. Extract it or prompt the user — it must match the pending peck record.
L15
The
otp field is the code delivered to the target's registered contact (email/SMS). It has a 10-minute TTL; after expiry the API returns EXPIRED.
L21
On success a
connection_id is issued and both duckling records are updated to reflect the active bond. Use /beak/spaceducks to list active bonds.{
"connection_id": "conn_r1s2t3u4",
"status": "bonded",
"peck_id": "peck_z9y8x7w6",
"requester_id": "dk_a1b2c3d4",
"target_id": "dk_b2c3d4e5",
"bonded_at": "2026-03-21T04:07:42Z"
}
5. Pulse — Send a heartbeat from an agent
An active Space Duck sends a pulse to confirm liveness. Use /beak/pulse from your agent process on a regular interval to maintain active-agent status in Mission Control.
import requests
import time
BEAK_API = "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod"
BEAK_KEY = "bk_xxxxxxxxxxxxxxxxxxxx"
DUCKLING_ID = "dk_a1b2c3d4"
PULSE_INTERVAL = 60 # seconds
def send_pulse():
"""Send a liveness heartbeat to the Space Duck platform."""
resp = requests.post(
f"{BEAK_API}/beak/pulse",
json={
"duckling_id": DUCKLING_ID,
"status": "active",
"meta": {
"agent_version": "1.0.0",
"uptime_seconds": int(time.time() - start_time)
}
},
headers={"Authorization": f"Bearer {BEAK_KEY}"},
timeout=10
)
return resp.status_code == 200
# ── Pulse loop ────────────────────────────────────────────────────────
start_time = time.time()
print("Starting pulse loop. Press Ctrl+C to stop.")
while True:
ok = send_pulse()
status = "✓ Pulse sent" if ok else "✗ Pulse failed — will retry"
print(f"[{time.strftime('%H:%M:%S')}] {status}")
time.sleep(PULSE_INTERVAL)
L7
PULSE_INTERVAL = 60 — recommended cadence. Mission Control marks an agent as "inactive" if no pulse is received for 5 consecutive minutes.
L14
status: "active" — other valid values are "paused" and "terminating". Use "terminating" during graceful shutdown so Mission Control reflects the intended state.
L15
meta — optional key-value bag visible in Mission Control. Use it for version, uptime, task counts, or any operator-relevant signal. Keep values under 256 chars.{
"status": "ok",
"duckling_id": "dk_a1b2c3d4",
"last_seen": "2026-03-21T04:12:00Z",
"active_bonds": 3,
"trust_tier": "T1"
}
6. Rotate Key — Generate a new Beak Key
Rotate your Beak Key on a schedule or after a suspected compromise. /beak/rotate invalidates the old key immediately and returns a fresh one. Update all services before the next request.
import requests
import os
BEAK_API = "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod"
BEAK_KEY = os.environ["SPACE_DUCK_BEAK_KEY"] # load from env, never hardcode
DUCKLING_ID = os.environ["SPACE_DUCK_DUCKLING_ID"]
# ── Rotate the Beak Key ───────────────────────────────────────────────
resp = requests.post(
f"{BEAK_API}/beak/rotate",
json={
"action": "rotate",
"duckling_id": DUCKLING_ID
},
headers={"Authorization": f"Bearer {BEAK_KEY}"}
)
data = resp.json()
if resp.status_code == 200:
new_key = data["new_beak_key"]
print(f"✓ Key rotated. New key (update your secrets store):")
print(f" {new_key}")
# ── IMPORTANT: update your secrets store immediately ──────────────
# e.g. aws secretsmanager put-secret-value --secret-id MyBeakKey \
# --secret-string "{\"beak_key\":\"" + new_key + "\"}"
else:
print(f"✗ Rotation failed: {data.get('message')}")
L4
Always load secrets from environment variables, not from hardcoded strings. Use
os.environ in Python or your cloud provider's secrets manager in production.
L8
/beak/rotate invalidates the current key immediately upon success. Any in-flight requests using the old key will 401 after this call completes.
L23
After rotation, update all downstream services (Lambdas, containers, CI/CD secrets) before the next scheduled pulse or peck. Schedule rotations during low-traffic windows.
{
"new_beak_key": "bk_newkeyxxxxxxxxxxxxxxxxx",
"duckling_id": "dk_a1b2c3d4",
"rotated_at": "2026-03-21T04:20:00Z",
"message": "Beak Key rotated. Previous key is now invalid."
}
Ready to build?
Install the SDK, explore all endpoints in the live API explorer, or read the full reference.