freee Accounting connector

Also available in Japanese.

The freee connector lets Kurahi agents read accounting data of the freee companies (offices) an administrator lists, through the freee API with a freee app the customer owns.

Property	Value
Plugin id	freee (bundled, off by default)
Access	Read-only, always. No write tool exists
Sign-in	OAuth 2.0 authorization code on a loopback redirect; client secret in the secret store
Token storage	Kurahi secret store (connector.freee.token)
Status	Available

Why there is no write tool

The task for this connector allowed creating a deal only as a draft. freee’s POST /deals has no draft or approval field: status (unsettled / settled) is the payment state, so a created deal always affects the books. Drafts exist only for general requests, expense claims and payment requests (draft: true on POST /approval_requests, /expense_applications, /payment_requests), which are workflow requests, not deals. So this release has no write tool at all.

What it reads

Tool	API	Returns
freee_companies_list	GET /companies	id, name, role, only for the configured companies
freee_deals_list	GET /deals	id, type, dates, amounts, payment status, partner id, line count; filters: type, status, partner, issue-date range; at most 100
freee_deal_get	GET /deals/{id}	the deal and its lines (account item, tax code, amount, description)
freee_partners_list	GET /partners	id, code, name, long name; at most 100
freee_account_items_list	GET /account_items	id, name, category (up to 500 listed)
freee_receipts_list	GET /receipts	metadata: id, status, issue date, file type, description; at most 100

Never read: companies that are not listed; receipt files (no download; the file URL is never returned); partner bank accounts, addresses and contacts; users; payroll (freee HR is a separate product and not covered).

Set up

1. In the freee app store developer console, create an app. Give it read permissions only for the resources above: deals (取引), partners (取引先), account items (勘定科目), receipts / file box (証憑/ファイルボックス) and companies (事業所), as the console labels them. Set the callback URL to http://localhost:<port>/callback.
2. Configure:

kurahi plugins enable freee
kurahi secrets set connector.freee.clientSecret
kurahi config set plugins.entries.freee.config '{
  "clientId": "<client id>", "companyIds": [1234567], "redirectPort": 8765
}' --json
kurahi freee status
kurahi freee login
kurahi freee probe

freee takes no scope parameter: permissions are chosen on the app and confirmed at consent; the token reports them as read / write. Every tool needs read.

Key	Default	Meaning
clientId	none	freee app Client ID
companyIds	none	Companies the agent may read; others are refused
redirectPort	none	Port of the registered callback URL (required)
ratePerSecond	3	Client-side request limit
probeIntervalMinutes	60	Health probe interval

Data handling

• Untrusted content. Descriptions, names and other customer text reach the model only inside the untrusted-content boundary.
• Audit. One row per call (connector.freee.<operation>): ids, counts, duration, error code. Never amounts, descriptions or names.
• Limits. freee counts calls per company per app per day (3,000 to 10,000 by plan) and answers 403 to bursts for about 10 minutes. The connector rate limits itself (3/s by default) and retries with backoff. Access tokens last 6 hours; refresh tokens are single use and rotated on every refresh.
• Endpoints. Only accounts.secure.freee.co.jp and api.freee.co.jp.

Status and revocation

The gateway probes GET /companies. kurahi freee logout revokes the token at /public_api/revoke and deletes it locally.

References

Official freee documentation: endpoints and client secret (getting-access-token), revoke (reference), token lifetimes (token_lifetime), paths, parameters, limits and the absence of a draft field (api-schema.json).

Setup notes: sign-in sends PKCE (ignored where unsupported) and uses a http://localhost callback URL, so register that callback for your freee app (freee documents urn:ietf:wg:oauth:2.0:oob for local testing and HTTPS URLs otherwise; an app that cannot register a localhost callback cannot sign in with this release). Revocation sends the client credentials with the token.