Concepts
Understand environments, connections, resources, operations, and usage.
Organization
The customer of AccountingKit. Every API key, environment, connection, operation, webhook, contract, and usage event belongs to exactly one organization.
Environment
Each organization has isolated test and live environments. API keys select an environment, so a
request cannot cross from test into live by changing a parameter. Test and live have separate
connections, webhook endpoints, usage, and idempotency records.
External account
Your stable identifier for your own customer or workspace. Supply it when creating a connect session. It remains provider-neutral and lets you map a connection back to your data model.
Provider app
The OAuth application your organization owns, initially a Xero developer app. Paid contracts register its client credentials and webhook signing key once. Connections retain the provider-app identity used for authorization, so token refresh and webhook routing always use the same app.
Connection
One authorized accounting organization, initially a Xero tenant. A connection stores its provider tenant ID, display name, scopes, sync state, metadata, and encrypted OAuth token envelope.
Resource
A normalized accounting object. Lists are served from the synchronized cache for predictable latency and pagination. Point reads contact the provider and refresh the cache. Normalized and encrypted raw provider payloads are retained for 30 days for support and reconciliation. Zero-retention connections perform live reads without persisting provider records and therefore do not support synchronization or durable automations.
Operation
A durable unit of background work. Automations, synchronization, webhook delivery, and retention run as operations with persisted attempts, leases, exponential backoff, and terminal dead-letter state.
Idempotency
Every public write and automation requires Idempotency-Key. Keys are scoped to the organization
and environment and retained for 30 days. The same key and request replay the original response.
Commercial contract and usage
Each organization has custom platform fees, included operations, included automation runs, overage rates, and a connection limit. Usage events are immutable and idempotent. Provider response bytes are metered per connection for Xero cost visibility but do not become billable usage automatically. Monthly rollups and statements support operator-reviewed invoicing without relying on a generic SaaS checkout module.