概要

OAuth2.0（Authorization Code Grant方式）を採用しています
freeeのIDとパスワードをアプリケーションに直接提供することなく認証可能です
セキュアな認証プロセスにより、ユーザーデータを安全に保護します

認可フロー

oauth2.0の遷移図 — Authorization Code Flowでのアクセストークン取得と更新

認可フロー詳細手順

1.初期アクセス

・ユーザーがアプリケーションにアクセス

2.認可URLへのリダイレクト

・URL形式

https://accounts.secure.freee.co.jp/public_api/authorize?

・必要パラメータ
　　・response_type=code
　　・client_id={アプリのclient_id}
　　・redirect_uri={コールバックURL}
　　・state={CSRF対策用ランダム文字列}
　　・prompt=select_company（事業所選択）

3.ユーザー認証とアクセス許可
　・freeeアカウントでのログイン
　・事業所選択
　・アプリケーションへの権限付与承認

4.認可コード取得
　・コールバックURLに認可コードが付与
　・レスポンス形式

5. アクセストークン取得リクエスト

POST https://accounts.secure.freee.co.jp/public_api/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={client_id}
&client_secret={client_secret}
&code={認可コード}
&redirect_uri={コールバックURL}

6.トークン取得

{
    "access_token": "xxx",
    "token_type": "bearer",
    "expires_in": 21600,
    "refresh_token": "yyy",
    "scope": "read write",
    "company_id": "123",
    "external_cid": "xyz"
}

トークン管理

アクセストークン

有効期限: 6時間
APIリクエスト時にはBearerトークンが必須
Authorization: Bearer {access_token} のように指定する

リフレッシュトークン

有効期限 90日
アクセストークン更新方法

POST https://accounts.secure.freee.co.jp/public_api/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={client_id}
&client_secret={client_secret}
&refresh_token={refresh_token}

注意事項
- 1回限り使用可能
- アクセストークン有効期限内での更新推奨
- 更新時に新しいリフレッシュトークンも発行されるので保存する

トークン無効化

POST https://accounts.secure.freee.co.jp/public_api/revoke
token={access_token or refresh_token}

実装のベストプラクティス

トークン管理
- アクセストークン、リフレッシュトークンを保管してください
- トークン有効期限の管理を行ってください
エラーハンドリング
- リフレッシュトークン失効時の再認可フロー
コールバックURL
- ローカルのテスト以外では`urn:ietf:wg:oauth:2.0:oob` は使用せず、自社の所有するhttpsのURLを指定してください

認可コード取得の補足

認可URLはアプリケーションは認可コードを取得するためのきっかけとなる画面です。freeeアプリストアのアプリ管理画面で確認します。

Top > アプリ管理 > アプリ詳細「基本設定」タブ

コールバックURLを指定します。コールバックURLは認可コードやアクセストークンを取得できた際に情報をアプリケーションに渡す場として機能、設定します。
1. ローカル環境でテストなどを行う場合は`urn:ietf:wg:oauth:2.0:oob` に設定し、認証用URLにアクセスします。
2. アプリケーションを配置しているサーバーがローカル環境ではなく、例えばSpreadsheetなどの場合は必要な値を入れます。
変更して下書き保存を行うと認証用URLが変わります。

ブラウザで認可コード取得する場合

1.テストを行う、フローを理解する目的の場合は、ブラウザで認可コードの取得ができます。アプリケーション利用者（freee user, リソースオーナー）が認証用URLにアクセスし、freeeのid, passwordでログインをすると、以下の画面となります。アクセス権とアクセスする事業所を選択したのちに、アプリケーションにアクセスを許可する意思として「許可する」をクリックします。

2.認可コードが表示されます。