Evenbead docs
Contents

Admin

18 operations. All areas

POST/v1/companies

Create a company (tenant) with its owner user and owner API key. Operator bootstrap token required.

  • Operation createCompany
  • Scope: operator token
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • name string, required
  • owner_name string, required
  • plan "solo" | "business" | "advanced" | "owned" ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting).
  • starter_chart "general" | "services" | "retail" | "empty" Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart).
  • periods boolean Create this fiscal year's and the next one's monthly periods (default true; false for a custom calendar)
Responses
  • 201 Created, with the starter chart applied and this fiscal year's and the next one's monthly periods (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/operator/companies/{id}/plan

A company's plan (ADR-0009) and the API rate limit it gives. Operator token only.

  • Operation getCompanyPlan
  • Scope: operator token
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Plan (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/operator/companies/{id}/plan

Set a company's plan (ADR-0009); its keys' and agents' rate limits follow on the next request. Audited in the company's log as the operator. Operator token only.

  • Operation setCompanyPlan
  • Scope: operator token
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body
  • plan "solo" | "business" | "advanced" | "owned", required ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting).
  • reason string, required
Responses
  • 200 Plan set (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/company

The caller's company

  • Operation getCompany
  • Scope: read
  • Read
Responses
  • 200 Company (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/me

Who the caller is: principal type, name, role, scopes, company

  • Operation getMe
  • Scope: read
  • Read
Responses
  • 200 Caller (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/company/kill-switch

Suspend or resume ALL agent writes for this company

  • Operation setKillSwitch
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • suspended boolean, required
  • reason string, required
Responses
  • 200 Updated (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/users

Create a human user

  • Operation createUser
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • name string, required
  • role "owner" | "cpa" | "accountant" | "staff", required
Responses
  • 201 Created (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/users

People in this company (names for the audit view)

  • Operation listUsers
  • Scope: read
  • Read
Responses
  • 200 Users (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/agents

Register an agent with scopes and a posting threshold

  • Operation createAgent
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • name string, required
  • scopes array of "read" | "propose" | "approve" | "admin", required
  • posting_threshold_cents integer, required Integer cents (100 = $1.00). Never a float.
  • owner_user_id string
Responses
  • 201 Created (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/agents

Registered agents with scopes, thresholds and revocation

  • Operation listAgents
  • Scope: read
  • Read
Responses
  • 200 Agents (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/agents/{id}/revoke

Revoke an agent; all its keys stop working on the next request

  • Operation revokeAgent
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 Revoked (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/keys

Mint an API key for a user or agent (secret returned once, stored hashed). Keys expire: people's after 365 days, agents' after 30 days by default (at most 90).

  • Operation createKey
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • principal_type "user" | "agent", required
  • user_id string
  • agent_id string
  • scopes array of "read" | "propose" | "approve" | "admin", required
  • expires_in_days integer Lifetime in days. Default: 365 for a person's key, 30 for an agent's (at most 90).
  • rate_limit_rpm integer | null This key's own rate budget in requests per minute (null: the company plan's limit).
Responses
  • 201 Created (NewApiKey)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/keys

API keys (never secrets): expiry, last use, rate budget, rotation, status. Admins see the company's keys; others their own.

  • Operation listKeys
  • Scope: read
  • Read
Parameters
  • include_ended query, boolean
  • user_id query, string
  • agent_id query, string
Responses
  • 200 Keys (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/keys/{id}

One API key (admins: any in the company; others: their own)

  • Operation getKey
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Key (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/keys/{id}/rotate

Rotate a live key (the company's admins, or the key's own holder: an agent can rotate the key it calls with). The successor has the same principal and scopes and a fresh lifetime; the old key keeps working for the overlap window (default 24 h, at most 7 days, 0 = at once). The new secret is returned once.

  • Operation rotateKey
  • Scope: read
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • overlap_seconds integer
  • expires_in_days integer Lifetime in days. Default: 365 for a person's key, 30 for an agent's (at most 90).
  • rate_limit_rpm integer | null Change the budget (the company's admins only); omitted: unchanged.
  • reason string
Responses
  • 201 Rotated (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/owner-invites/claim

The owner claims a company an accounting firm created: send the invitation (ebi_...) as the Bearer token. Returns the owner's key once; the firm never sees it. Single use; void after 14 days or once the company revokes the firm's access.

  • Operation claimOwnerInvite
  • Scope: owner invitation
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • expires_in_days integer Lifetime in days. Default: 365 for a person's key, 30 for an agent's (at most 90).
Responses
  • 201 Claimed (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/keys/{id}/revoke

Revoke one API key, effective on the next request

  • Operation revokeKey
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 Revoked (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/company/fiscal-year

Set the fiscal year start month (refused while any period is hard-locked). Applies to reports, year-to-date and fiscal-year period locks.

  • Operation setFiscalYear
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • start_month integer, required
  • reason string
Responses
  • 200 Updated (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)