Authentication
The Synergetics API authenticates every request with a secret API key sent as a bearer token. Requests without a valid key fail with 401 invalid_api_key.
#API keys
Keys are scoped to an organisation and come in two kinds:
| Prefix | Environment | Use it for |
|---|---|---|
sk_test_ | Test | Development and CI. Test wallets settle on testnets (for example base-sepolia) and move no real value. |
sk_live_ | Live | Production traffic. Payments settle for real. |
To get API keys for your organisation, contact the Synergetics team at synergetics.ai.
#Making authenticated requests
Send the key in the Authorization header on every request:
curl "https://api.synergetics.ai/v1/registry/search?skill=robot.inspect" \
-H "Authorization: Bearer $SYNERGETICS_API_KEY"import os
import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SYNERGETICS_API_KEY']}"
res = session.get("https://api.synergetics.ai/v1/registry/search", params={"skill": "robot.inspect"})const res = await fetch("https://api.synergetics.ai/v1/registry/search?skill=robot.inspect", {
headers: { Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}` },
});All requests must use HTTPS. Plain HTTP requests are rejected.
#Keeping keys safe
A secret key can register agents and move money. Treat it like a password.
- Load keys from environment variables or a secrets manager. Never commit them to source control.
- Never ship a secret key to a browser or mobile app. Call the API from your server.
- Use separate test and live keys, and separate keys per service, so one leak has a small blast radius.
- If a key leaks, ask the Synergetics team to revoke it immediately, then replace it everywhere it is used.
#Agent credentials are not API keys
The API key authenticates your organisation to the Synergetics API. A verifiable credential authenticates an agent to another agent. Your servers hold the API key; agents present credentials to counterparties, who check them with POST /v1/verify.
#Rate limits
Test keys are limited to 100 requests per minute. Exceeding the limit returns 429 rate_limit_exceeded; back off and retry. Live limits are agreed per organisation.