Authentication and accounting firms
Every request carries one credential as a Bearer token. The database itself binds each request to that credential: a request can only see the companies the credential reaches, and the audit log records the principal behind it.
Credentials
| Credential | Looks like | Who holds it | Lifetime |
|---|---|---|---|
| Company API key | eb_ + 43 characters | A person or an agent in one company | People 365 days; agents 30 days by default, at most 90 |
| Web session | ebs_... | A person signed in to the web app | 8 hours idle, 7 days at most, never past its key |
| Firm key | eb_ + 43 characters | A firm member or firm agent | Same rules as company keys |
| Firm session | ebf_... | A firm member in the accountant console | 8 hours idle, 7 days at most |
| Owner invitation | ebi_... | The owner of a company a firm created | 14 days, single use |
Only a hash of each secret is stored. Secrets are shown once, at creation.
curl -s https://api.evenbead.com/v1/me -H "Authorization: Bearer $EVENBEAD_KEY"Agent identity
Agent keys must send the model on every write, and should send a run id so a run can be traced in the audit log:
X-Agent-Model: the model name and version, for exampleclaude-opus-5-5.X-Agent-Run-Id: your run, job or prompt id.
Over MCP, clients that cannot set headers put the same values in the request's _meta as dev.evenbead/model and dev.evenbead/run_id.
Accounting firms
Firms reach a client's books only through a grant the client's own people give (POST /v1/firm-access). The grant's scopes are the ceiling for every firm member and firm agent in that company, and the client can revoke it at any time (effective on the firm's next request).
A firm credential acts in one client per request, named by a header:
curl -s "https://api.evenbead.com/v1/proposals?status=pending" \
-H "Authorization: Bearer $FIRM_KEY" \
-H "X-Evenbead-Company: <client company id>"Inside the client the firm member or agent acts as its own identity there, with every rule of that company applied: scopes, thresholds, period locks, the audit log. Over MCP, the client goes in _meta as dev.evenbead/company.
Firm-level operations (/v1/firm/...) take a firm key or firm session without the header: members, firm keys, firm agents and their per-client assignments and thresholds, the client console, bulk period locks, the firm kill switch and the firm's own audit chain.
Clients a firm creates
A firm admin can create a client company (POST /v1/firm/clients). The firm never receives a company key: it gets a single-use owner invitation to hand to the owner privately. The owner claims it in the web app at /app/claim, or with:
curl -s https://api.evenbead.com/v1/owner-invites/claim -X POST \
-H "Authorization: Bearer ebi_..." -H "Idempotency-Key: claim-owner-001" \
-H "Content-Type: application/json" -d '{}'The owner key comes back once. If the claim says the invitation was already claimed, someone else used it: revoke the firm's access and contact support@evenbead.com.
Revocation and kill switches
- Revoking a key, an agent, a session or a firm member takes effect on the next request.
- A company's kill switch suspends every agent write in that company; a firm's kill switch suspends every firm agent's writes in every client.
- Refused requests by a known credential are written to the audit log too.