Authentication
Create an sk_ API key, authenticate every request, and rotate or expire keys without breaking production.
One key unlocks the whole API. Every request to Buda's REST API, MCP endpoint, and embed flows authenticates with a single API key tied to your account. Create it once in the dashboard, send it as a Bearer token, and you're calling hosted agents in minutes.
Create an API key
Open Settings → API Keys
In the dashboard, go to Settings → API Keys and choose Create new key.
Name it and set an expiry
Give the key a recognizable name (for example production-backend) and pick an expiry: Never, 7 days, 30 days, 90 days, or 365 days. Short-lived keys are safer for testing and CI.
Copy the key now
The full key — prefixed sk_ — is shown once, right after creation. Copy it into your secret store immediately; Buda only stores a masked version afterward, so it can never be revealed again.
If you miss the one-time reveal, delete the key and create a new one. There is no way to recover the full value later.
Use the key
Send the key as a Bearer token in the Authorization header. The base URL is /api/v1.
# Verify your key resolves to your account
curl https://buda.im/api/v1/users/me \
-H "Authorization: Bearer sk_your_api_key"// Node / TypeScript
const API_BASE = "https://buda.im/api/v1";
const headers = {
Authorization: `Bearer ${process.env.BUDA_API_KEY}`,
"Content-Type": "application/json",
};
const me = await fetch(`${API_BASE}/users/me`, { headers }).then((r) => r.json());A valid key resolves to the owning user; a missing or invalid key returns 401 Unauthorized. Buda records the time of each key's most recent request so you can spot keys that are still in use before deleting them.
Rotation and expiry
- Expiry is set at creation and cannot be extended. To "renew," create a new key and retire the old one.
- Rotate by creating the replacement first, deploying it, then deleting the previous key — so there's no gap in service.
- Delete a key any time from Settings → API Keys. Deletion is immediate and permanent: in-flight requests using that key start failing right away.
Security best practices
- Treat keys like production secrets. Never hardcode them in frontend or mobile code, and never commit them to a repo.
- Keep environments separate. Use distinct keys for test, staging, and production so you can revoke one without disrupting the others.
- Never ship your key to a browser. For client-side agent chat, use short-lived embed tokens instead of your
sk_key. - Rotate on exposure. If a key may have leaked, delete it immediately and issue a new one.