Kozotai 会計の会計データに、外部アプリケーションから安全にアクセスするための Public API について説明します。
Kozotai 会計は OAuth 2.0 に準拠した Public API を提供しています。これにより、外部アプリケーションはユーザーの同意のもとで会社の会計データ（仕訳・勘定科目・証憑ファイルなど）を読み書きできます。
ベースURL:
https://v1.kozotai.com認可方式: OAuth 2.0 Authorization Code フロー（PKCE 必須）
認証方式: アクセストークンを
Authorization: Bearer <トークン>ヘッダーで送信
アプリはユーザー（会社）ごとに個別の同意を得た上で、許可された範囲（スコープ）内でのみデータへアクセスできます。ユーザーはいつでも連携を確認・解除できます。
OAuth クライアントは、必要な権限をスコープとして要求します。
スコープ | 内容 |
|---|---|
| ユーザー識別子・プロフィール情報の取得（常時付与） |
| 仕訳・勘定科目などの読み取り |
| 仕訳・マスターデータの作成・更新 |
| 証憑ファイルの取得 |
| 証憑ファイルのアップロード |
外部アプリから API を利用するには、まず開発者ポータルで OAuth クライアント（アプリ）を登録します。
「新規作成」からアプリ情報を入力する
アプリ名: ユーザーの同意画面に表示される名称
説明（任意）: アプリの用途の簡単な説明
ホームページ URL（任意）
Redirect URI: 認可コードの受け取り先 URL（複数登録可、改行区切り）
Scopes: アプリが要求する権限を選択
「作成する」を押すと Client ID と Client Secret が発行される
Client Secret はこの時点でのみ表示されます。安全な場所に保管してください（表示後は再発行しない限り確認できません）。
作成直後のアプリは「下書き」状態で、この状態では認可フローを利用できません。アプリ詳細ページ（/developer/apps/{appId}）から「有効化」を行うことで、実際に OAuth 認可・トークン発行が可能になります。
アプリのステータス:
ステータス | 説明 |
|---|---|
下書き | 作成直後。認可フローは利用不可 |
有効 | 認可フロー・API 呼び出しが可能 |
停止 | 既存のトークン・連携をすべて無効化。以降の認可も不可 |
アプリ詳細ページの「認証情報」タブから以下を行えます。
Client ID の確認
Client Secret の再発行（再発行すると既存の Secret は即時失効するため、連携アプリ側の設定も更新が必要）
認可リクエスト: ユーザーを
https://oauth.kozotai.com/authorizeへリダイレクトする（client_id/redirect_uri/scope/code_challenge（S256）などを付与）ユーザー同意: ユーザーはログイン後、アクセスを許可する会社を選び、要求スコープを確認して許可・拒否を行う
認可コードの受け取り: 許可されると、登録済みの Redirect URI へ認可コード付きでリダイレクトされる
アクセストークンの取得:
https://oauth.kozotai.com/tokenへ Client ID/Secret（client_secret_basic）と認可コード、PKCE のcode_verifierを送信し、アクセストークン（および Refresh Token）を取得するトークンの更新: アクセストークンの有効期限が切れた場合は
grant_type=refresh_tokenで/tokenエンドポイントから再取得する
取得したアクセストークンを Authorization: Bearer <アクセストークン> として付与し、https://v1.kozotai.com 配下のエンドポイントを呼び出します。要求したスコープの範囲を超えるエンドポイントはアクセスできません。
個別のエンドポイド仕様は OpenAPI ドキュメント（https://v1.kozotai.com/{バージョン}/openapi）を参照してください。
API のパスには /20260803 のような日付形式のバージョンを含めます（例: https://v1.kozotai.com/20260803/accounts）。
破壊的変更を行う場合は新しいバージョンのパスが発行され、既存バージョンとは別に提供されます
利用中のバージョンは固定で動作し続けるため、実装時は必ず具体的なバージョンを指定してください
バージョン情報
現在利用可能なバージョンは以下の通りです。
バージョン名 | ドキュメント | APIエンドポイント |
20260803 |
会社のユーザーは https://app.kozotai.com/apps/connections から、許可済みのアプリ連携を一覧で確認し、不要になった連携をいつでも解除できます。解除すると、そのアプリが発行済みのトークンはすべて無効になります。
デモ環境等の提供は現時点ではありません。
テストを行う際はKOZOTAIの会社を新規で作成した上で実際の環境でお試しください。（無料条件内であれば費用等掛かりません）