カオナビAPI連携ガイド【2026年版】認証とエンドポイント徹底解説

2026年7月9日

バックオフィス職での転職を考えている人

スポンサードリンク

その頑張り、評価されていますか？

バックオフィスの努力が"経営の要"として評価される会社、あります

業務効率化を調べる時間、電子帳簿保存法を勉強する時間、締め作業で残業する夜——バックオフィスを"経営の要"として評価する会社と、"コスト部門"扱いする会社は、驚くほど別世界です。今のあなたの努力は、正しく評価されていますか？

▷「業務改善を頑張るほど、なぜか報われない気がする」あなたへ

Backup Careerは事務職転職に特化した支援サービス。無料の"仕事適性診断"を受けると、今の職種の延長線だけでなく"経理→労務"や"総務→秘書"などの隣接領域を含めた自分の伸びしろが可視化されます。担当のキャリアアドバイザーはマンツーマンで、"大手エージェントで求人メールだけ送られた"経験のある方こそ、肩を張らないカジュアルな相談ができます。ブラック企業を紹介しない方針＋入社後の定着率93.5%で、「今度こそ長く続けられる会社」に出会えます。

Backup Career｜事務職転職に特化のオンライン支援・満足度4.3・定着率93.5%

Backup Careerで無料キャリア相談を予約する

今すぐ辞める必要はありません。まず"適性診断だけ"受けて自分の市場価値を測る場所として使えます。今日の10分が、来年の働き方を変えます。

Contents

1 エンドポイント一覧
2 OAuth 2.0 認可コードフロー
- 2.1 トークンの有効期限とリフレッシュ
3 API キー方式
- 3.1 方式の選び方
4 アクセス手順と認証
5 テストデータ取得例
6 社員情報取得コード例
- 6.1 Python（requests）
- 6.2 Node.js（axios）
7 社員情報更新コード例
- 7.1 Python（PATCH）
- 7.2 Node.js（axios PATCH）
8 主なステータスコードと推奨対応
9 レートリミットの確認方法
10 データ同期パターン選択指針
11 通信・認証の安全対策
12 実装後チェックリスト

スポンサードリンク

エンドポイント一覧

以下は 2026 年時点で公開されている主要エンドポイントです。本番環境 のプレフィックスは https://api.kaonavi.com、サンドボックス環境 は https://sandbox-api.kaonavi.com となります。

エンドポイント	メソッド	主な用途
`/v1/employees`	GET	社員一覧取得（ページング対応）
`/v1/employees/{employee_id}`	GET	個別社員情報取得
`/v1/employees/{employee_id}`	PATCH	社員属性の部分更新
`/v1/organizations`	GET	組織ツリー（階層構造）取得
`/v1/custom_fields`	GET	カスタム項目定義取得
`/v1/batch/jobs`	POST	バッチ処理ジョブ登録（大量更新向け）

ポイント
- 全エンドポイントは JSON 形式でリクエスト・レスポンスをやり取りし、標準的な HTTP ステータスコードで成功/失敗が示されます。
- サンドボックス環境のデータは本番データに影響せず、ダミー社員レコード（約 100 件）が用意されています。

認証方式と取得手順

API を呼び出すには OAuth 2.0 の認可コードフロー または API キー のいずれかを利用します。ここではそれぞれの取得手順と、実装時に意識すべきポイントを解説します。

OAuth 2.0 認可コードフロー

OAuth 2.0 はユーザー権限を委譲できるため、スコープ単位でアクセス範囲を限定できます。以下の手順でトークンを取得します。

開発者ポータルでアプリ登録
アプリ名・リダイレクト URI を入力し「登録」すると client_id と client_secret が発行されます。
認可エンドポイントへリクエスト

text GET https://auth.kaonavi.com/oauth/authorize? response_type=code& client_id={CLIENT_ID}& redirect_uri={REDIRECT_URI}& scope=employee.read employee.write

ユーザーが認可 → 認可コード取得
リダイレクト先 URL に code=xxxx が付与されます。
トークンエンドポイントでアクセストークン取得

http POST https://auth.kaonavi.com/oauth/token Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code& code={AUTH_CODE}& redirect_uri={REDIRECT_URI}& client_id={CLIENT_ID}& client_secret={CLIENT_SECRET}

取得したトークンをリクエストヘッダーに付与

http Authorization: Bearer {ACCESS_TOKEN}

トークンの有効期限とリフレッシュ

アクセストークン は発行から 1 時間（60 分）有効です。
リフレッシュトークン は最長で 30 日間保持でき、grant_type=refresh_token を用いて新しいアクセストークンを取得できます。実装時は有効期限切れ前に自動的にリフレッシュするロジックを組み込むことが推奨されます。

API キー方式

API キー方式はサーバートゥサーバー連携に適しており、トークン取得手順が不要です。

キーの発行
開発者ポータル → 「API キー」タブ → 「新規キー作成」ボタンで X-Api-Key が生成されます。
リクエストヘッダーへの設定例（サンドボックス）

http GET https://sandbox-api.kaonavi.com/v1/employees X-Api-Key: {YOUR_API_KEY}

方式の選び方

条件	推奨認証方式
ユーザー権限が必要でスコープ制御したい	OAuth 2.0
バックエンドジョブ・バッチ処理のみ	API キー

サンドボックス環境でのテスト方法

本番データに影響を与えずに動作確認したい場合は、カオナビが提供するサンドボックス環境を利用します。ここではアクセス手順とテストデータ取得例を示します。

アクセス手順と認証

エンドポイント は https://sandbox-api.kaonavi.com で統一されます。
認証は本番と同じ auth.kaonavi.com を使用し、サンドボックス用に発行したクライアント ID/シークレットまたは API キーを利用します。

⚠️ 現時点で公式に提供されている「sandbox-auth」エンドポイントはありません。認証は上記の通り本番と同一です。

テストデータ取得例

サンドボックスには約 100 件のダミー社員レコードが用意されています。以下のリクエストでページング付きに取得可能です。

GET https://sandbox-api.kaonavi.com/v1/employees?page=1&amp;limit=20
Authorization: Bearer {SANDBOX_ACCESS_TOKEN}

GET https://sandbox-api.kaonavi.com/v1/employees?page=1&limit=20

Authorization: Bearer {SANDBOX_ACCESS_TOKEN}

レスポンス は本番と同一形式の JSON が返ります。
サンドボックスは 30 分間のアイドルタイムアウト があるため、長時間テストする場合はトークンを再取得してください。

実装サンプル（Python・Node.js）

実際に API を呼び出すコード例として、社員情報取得と更新の 2 パターンを Python と Node.js で示します。エラーハンドリングやレートリミット対策も合わせて紹介します。

社員情報取得コード例

Python（requests）

import os
import time
import requests

API_BASE = &quot;https://sandbox-api.kaonavi.com/v1&quot;
ACCESS_TOKEN = os.getenv(&quot;KAONAVI_ACCESS_TOKEN&quot;)  # 環境変数から取得

def get_employee(employee_id: str):
    &quot;&quot;&quot;社員 ID に紐づく情報を取得する。&quot;&quot;&quot;
    url = f&quot;{API_BASE}/employees/{employee_id}&quot;
    headers = {&quot;Authorization&quot;: f&quot;Bearer {ACCESS_TOKEN}&quot;}
    resp = requests.get(url, headers=headers)

    if resp.status_code == 200:
        return resp.json()
    else:
        handle_error(resp)

def handle_error(resp):
    &quot;&quot;&quot;ステータスコード別に例外を送出する。&quot;&quot;&quot;
    if resp.status_code == 401:
        raise RuntimeError(&quot;認証エラー：トークンが無効または期限切れ&quot;)
    elif resp.status_code == 429:
        # レートリミット超過時は Retry-After ヘッダーで待機
        wait = int(resp.headers.get(&quot;Retry-After&quot;, &quot;5&quot;))
        time.sleep(wait)
        raise RuntimeError(f&quot;レートリミット超過：{wait}s 後に再実行してください&quot;)
    else:
        raise RuntimeError(f&quot;API エラー {resp.status_code}: {resp.text}&quot;)

# 使用例
if __name__ == &quot;__main__&quot;:
    emp = get_employee(&quot;12345&quot;)
    print(emp)

import os

import time

import requests

API_BASE = "https://sandbox-api.kaonavi.com/v1"

ACCESS_TOKEN = os.getenv("KAONAVI_ACCESS_TOKEN") # 環境変数から取得

def get_employee(employee_id: str):

"""社員 ID に紐づく情報を取得する。"""

url = f"{API_BASE}/employees/{employee_id}"

headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

resp = requests.get(url, headers=headers)

if resp.status_code == 200:

return resp.json()

else:

handle_error(resp)

def handle_error(resp):

"""ステータスコード別に例外を送出する。"""

if resp.status_code == 401:

raise RuntimeError("認証エラー：トークンが無効または期限切れ")

elif resp.status_code == 429:

# レートリミット超過時は Retry-After ヘッダーで待機

wait = int(resp.headers.get("Retry-After", "5"))

time.sleep(wait)

raise RuntimeError(f"レートリミット超過：{wait}s 後に再実行してください")

else:

raise RuntimeError(f"API エラー {resp.status_code}: {resp.text}")

# 使用例

if __name__ == "__main__":

emp = get_employee("12345")

print(emp)

Node.js（axios）

require('dotenv').config();
const axios = require('axios');

const API_BASE = 'https://sandbox-api.kaonavi.com/v1';
const ACCESS_TOKEN = process.env.KAONAVI_ACCESS_TOKEN;

async function getEmployee(employeeId) {
  /** 社員 ID に紐づく情報を取得する。 */
  try {
    const res = await axios.get(`${API_BASE}/employees/${employeeId}`, {
      headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
    });
    return res.data;
  } catch (err) {
    handleError(err);
  }
}

function handleError(error) {
  if (!error.response) throw new Error('ネットワークエラー');
  const { status, data, headers } = error.response;

  if (status === 401) throw new Error('認証エラー：トークンが無効または期限切れ');
  if (status === 429) {
    const wait = parseInt(headers['retry-after'] || '5', 10);
    setTimeout(() =&gt; {
      console.warn(`レートリミット超過 → ${wait}s 後に再実行`);
    }, wait * 1000);
    throw new Error('レートリミット超過');
  }
  throw new Error(`API エラー ${status}: ${JSON.stringify(data)}`);
}

// 使用例
getEmployee('12345')
  .then(console.log)
  .catch(console.error);

require('dotenv').config();

const axios = require('axios');

const API_BASE = 'https://sandbox-api.kaonavi.com/v1';

const ACCESS_TOKEN = process.env.KAONAVI_ACCESS_TOKEN;

async function getEmployee(employeeId) {

/** 社員 ID に紐づく情報を取得する。 */

try {

const res = await axios.get(`${API_BASE}/employees/${employeeId}`, {

headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },

});

return res.data;

} catch (err) {

handleError(err);

}

function handleError(error) {

if (!error.response) throw new Error('ネットワークエラー');

const { status, data, headers } = error.response;

if (status === 401) throw new Error('認証エラー：トークンが無効または期限切れ');

if (status === 429) {

const wait = parseInt(headers['retry-after'] || '5', 10);

setTimeout(() => {

console.warn(`レートリミット超過 → ${wait}s 後に再実行`);

}, wait * 1000);

throw new Error('レートリミット超過');

}

throw new Error(`API エラー ${status}: ${JSON.stringify(data)}`);

}

// 使用例

getEmployee('12345')

.then(console.log)

.catch(console.error);

社員情報更新コード例

Python（PATCH）

def update_employee(employee_id: str, payload: dict):
    &quot;&quot;&quot;社員属性の部分更新を行う。&quot;&quot;&quot;
    url = f&quot;{API_BASE}/employees/{employee_id}&quot;
    headers = {
        &quot;Authorization&quot;: f&quot;Bearer {ACCESS_TOKEN}&quot;,
        &quot;Content-Type&quot;: &quot;application/json&quot;,
    }
    resp = requests.patch(url, json=payload, headers=headers)

    if resp.status_code == 200:
        return resp.json()
    else:
        handle_error(resp)

# 更新例
if __name__ == &quot;__main__&quot;:
    updated = update_employee(
        &quot;12345&quot;,
        {
            &quot;department&quot;: &quot;マーケティング部&quot;,
            &quot;custom_fields&quot;: {&quot;skill_level&quot;: &quot;中級&quot;},
        },
    )
    print(updated)

def update_employee(employee_id: str, payload: dict):

"""社員属性の部分更新を行う。"""

url = f"{API_BASE}/employees/{employee_id}"

headers = {

"Authorization": f"Bearer {ACCESS_TOKEN}",

"Content-Type": "application/json",

}

resp = requests.patch(url, json=payload, headers=headers)

if resp.status_code == 200:

return resp.json()

else:

handle_error(resp)

# 更新例

if __name__ == "__main__":

updated = update_employee(

"12345",

{

"department": "マーケティング部",

"custom_fields": {"skill_level": "中級"},

)

print(updated)

Node.js（axios PATCH）

async function updateEmployee(employeeId, payload) {
  /** 社員属性の部分更新を行う。 */
  try {
    const res = await axios.patch(`${API_BASE}/employees/${employeeId}`, payload, {
      headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
    });
    return res.data;
  } catch (err) {
    handleError(err);
  }
}

// 更新例
updateEmployee('12345', {
  department: 'マーケティング部',
  custom_fields: { skill_level: '中級' },
})
  .then(console.log)
  .catch(console.error);

async function updateEmployee(employeeId, payload) {

/** 社員属性の部分更新を行う。 */

try {

const res = await axios.patch(`${API_BASE}/employees/${employeeId}`, payload, {

headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },

});

return res.data;

} catch (err) {

handleError(err);

}

// 更新例

updateEmployee('12345', {

department: 'マーケティング部',

custom_fields: { skill_level: '中級' },

})

.then(console.log)

.catch(console.error);

エラーハンドリングとレートリミット対策

API 呼び出しで遭遇しやすいエラーと、その具体的な対応策をまとめます。実装時に例外処理を一元化すると保守性が向上します。

主なステータスコードと推奨対応

ステータス	主な原因	推奨対応
400	パラメータ不正・必須項目欠如	リクエスト前にバリデーションを実施
401	アクセストークン無効または期限切れ	OAuth の場合はリフレッシュトークンで再取得、API キーの場合はキー再発行
403	スコープ不足・IP 制限	必要スコープを付与し、コンソールで IP ホワイトリスト設定
404	指定リソースが存在しない	ID が正しいか確認し、削除済みの場合は代替ロジック
429	レートリミット超過（公式では約 60 リクエスト/分）	`Retry-After` ヘッダーを参照して指数バックオフで再試行

レートリミットの確認方法

各レスポンスに X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が含まれます。
429 が返った場合は必ず Retry-After（秒数）を取得し、その時間だけ待機してからリトライしてください。
安定運用のため、1 分あたり 50 件程度に抑える「余裕設計」を推奨します。

運用・セキュリティベストプラクティス

API 連携は機能だけでなく、情報漏洩や障害拡大を防ぐための運用ルールが重要です。以下の指針を参考に、システム全体の安全性と保守性を高めましょう。

データ同期パターン選択指針

パターン	メリット	デメリット
リアルタイム（Webhook + 即時取得）	変更が即座に反映され、ユーザー体験向上	呼び出し回数が増えるためレートリミットへの注意が必要
バッチ（定期的に全件取得）	処理負荷を平準化でき、障害時のロールバックが容易	変更反映までタイムラグが発生

選択は「データ鮮度」 vs 「安定運用」のトレードオフで判断してください。

通信・認証の安全対策

TLS：必ず HTTPS（TLS 1.2 以上）を使用し、証明書検証をスキップしない。
IP 制限：カオナビ管理コンソールから自社サーバーの固定 IP をホワイトリスト登録。
シークレット管理：client_secret・API_KEY は環境変数、AWS Secrets Manager など安全な場所に保管し、コードベースへ埋め込まない。
ログ出力：以下情報を必ずロギングし、監査可能にする。
タイムスタンプ、エンドポイント、HTTP メソッド、ステータスコード
X-Request-ID（リクエスト追跡用）

実装後チェックリスト

[ ] 認証情報 が環境変数またはシークレット管理サービスに格納されている。
[ ] アクセストークン取得ロジックが自動的に有効期限を確認し、必要時にリフレッシュできる。
[ ] 各エンドポイントの 成功 / 失敗 ケースでユニットテスト／統合テストが作成済み。
[ ] 429 発生時の 指数バックオフ 実装と、ヘッダーからリセット時間を取得するロジックがある。
[ ] TLS・IP 制限・ログポリシーが運用ドキュメントに明記され、定期的にレビューしている。

まとめ

カオナビ API は HR コアデータへの高速かつ安全なアクセス手段を提供します。本稿で示したエンドポイント一覧と認証フロー、サンドボックスでのテスト手順を踏めば、実装前に十分な検証が可能です。Python と Node.js のサンプルコードは、トークン取得・リフレッシュ・エラーハンドリングまで網羅しているため、自社システムへの組み込み時の雛形として活用できます。

運用面では リアルタイム vs バッチ の同期方式選択、TLS/IP 制限・シークレット管理といったセキュリティベストプラクティスを守ることが鍵です。チェックリストを活用し、実装完了後も定期的なレビューを行うことで、安定した API 連携を継続できます。

ぜひ本ガイドを手引きに、カオナビ API を活用した人事システムの高度化に挑戦してください。

スポンサードリンク

バックオフィス職での転職を考えている人

スポンサードリンク

その頑張り、評価されていますか？

バックオフィスの努力が"経営の要"として評価される会社、あります

▷「業務改善を頑張るほど、なぜか報われない気がする」あなたへ

Backup Careerで無料キャリア相談を予約する

今すぐ辞める必要はありません。まず"適性診断だけ"受けて自分の市場価値を測る場所として使えます。今日の10分が、来年の働き方を変えます。

-カオナビ

comment コメントをキャンセル

: カオナビ

2026年最新！カオナビ無料トライアル申し込み手順と特典

転職活動や採用プロセスの効率化に注目されている「カオナビ」。7日間無料トライアルで全機能を試せます。

: カオナビ

2026年版カオナビ料金プラン比較と中小企業向け選び方

2026年のカオナビ料金プラン比較。人事DXとタレントマネジメントの違い、中小企業向けコストパフォーマンスや選び方を具体的に解説します。

: カオナビ

中小企業向けタレントマネジメント『カオナビ』導入効果と事例解説

カオナビは中小企業向けタレントマネジメントツールで、スキル可視化・評価デジタル化・CDP分析を提供し、導入事例として魚沼市役所と関西大学が業務効率化と人材活用の効果を実証しています。

: カオナビ

中小企業向けカオナビタレントマネジメント導入手順ガイド

中小企業向けにカオナビタレントマネジメントの導入手順を解説。ニーズ分析から初期設定、研修計画、導入後のサポート体制まで具体的なステップと実績事例を紹介。

: カオナビ

カオナビで評価シートカスタマイズ｜中小企業の人事業務効率化

中小企業の人事評価業務における課題と、カオナビで実現する評価シートカスタマイズの解決策。ドラッグ＆ドロップ機能やAIによる自動集計・コメントチェックを活用した効率化方法が解説されています。

カオナビ人事評価機能の設定手順と活用ベストプラクティス

Looker Studio データソース接続と認証・最適化ガイド

カオナビAPI連携ガイド【2026年版】認証とエンドポイント徹底解説

エンドポイント一覧

認証方式と取得手順

OAuth 2.0 認可コードフロー

トークンの有効期限とリフレッシュ

API キー方式

方式の選び方

サンドボックス環境でのテスト方法

アクセス手順と認証

テストデータ取得例

実装サンプル（Python・Node.js）

社員情報取得コード例

Python（requests）

Node.js（axios）

社員情報更新コード例

Python（PATCH）

Node.js（axios PATCH）

エラーハンドリングとレートリミット対策

主なステータスコードと推奨対応

レートリミットの確認方法

運用・セキュリティベストプラクティス

データ同期パターン選択指針

通信・認証の安全対策

実装後チェックリスト

まとめ

OAuth 2.0 認可コードフロー