33
Auth & SecurityRoot Key & API Authentication
How SAPIX_ROOT_KEY works, how to authenticate calls, and how to move from open to locked mode.
Prerequisite: Lesson 2 complete
What you'll learn
- ✓Open mode (no root key) vs auth mode (root key set)
- ✓Authorization: Bearer <SAPIX_ROOT_KEY> header on every request
- ✓401 Unauthorized when header is missing in auth mode
- ✓Root key is the master credential — never use in app code
- ✓Restart required to activate auth mode
Challenge
Confirm auth mode is active. Call without header — confirm 401. Call with correct header — confirm 200.
Interactive Walkthrough
What you'll learn
How SAPIX_ROOT_KEY works, how to authenticate API calls, and how to move from open mode to locked mode.
Two modes
| Mode | What it means |
|---|---|
| Open mode | No SAPIX_ROOT_KEY set — all API calls allowed |
| Auth mode | SAPIX_ROOT_KEY set — all calls need Authorization: Bearer <key> |
Set the root key
Add to docker-compose.yml:
`yaml
environment:
SAPIX_ROOT_KEY: spx_root_YOUR_HEX_HERE
`
Restart: docker compose down && docker compose up -d
Authenticate every request
curl -s http://localhost:7475/v1/health \
-H "Authorization: Bearer spx_root_YOUR_HEX_HERE"Without the header in auth mode:
`json
{"error": "Unauthorized", "code": 401}
`
What root key can do
- Everything. Create/delete agents, write/read/delete records, manage API keys, restart, checkpoint, all admin operations.
- Never use it in client-side code or share it with services. It is your one master credential.
Verify auth is enforced
# Should return 401 when auth mode is active
curl -s http://localhost:7475/v1/agents | python3 -m json.toolChallenge
Confirm your instance is running in auth mode. Try one API call without the header — confirm 401. Try with the correct header — confirm 200.
---