APIトークンと認証

kintone REST API を利用する際、リクエストを送信するだけではデータにアクセスできません。認証の仕組みを正しく理解し、適切に設定する必要があります。

kintone では主に 3 つの認証方法が提供されており、利用する場面や目的に応じて使い分けます。認証方法を誤ると、セキュリティ上のリスクや、想定外のアクセス権の問題が発生する可能性があります。

この記事では、kintone REST API の認証方法の仕組みと使い分け、セキュリティのベストプラクティスを解説します。

認証方法の種類と使い分け

kintone REST API では、以下の 3 つの認証方法が利用できます。

API トークン認証

API トークンとは

API トークンは、アプリごとに発行される認証用の文字列です。ユーザーのログイン情報を使わずに、プログラムから安全に API を呼び出すことができます。

API トークンの主な特徴:

• アプリ単位で発行される（1 つのトークンは 1 つのアプリに紐づく）
• 権限を細かく制御できる（閲覧のみ、追加のみ、など）
• 複数のトークンを発行でき、用途ごとに分けて管理できる
• トークンを無効化（削除）すれば、即座にアクセスを遮断できる

API トークンの発行手順

1. 対象のアプリを開く
2. アプリの設定（歯車アイコン）をクリック
3. 設定 タブの API トークン をクリック
4. 生成する ボタンをクリック
5. 必要なアクセス権にチェックを入れる
6. 保存 → アプリを更新 をクリック

API トークンのアクセス権

API トークンには以下のアクセス権を設定できます:

API トークンを使ったリクエスト

Node.js（fetch）の場合

const KINTONE_DOMAIN = 'your-subdomain.cybozu.com';
const API_TOKEN = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
const APP_ID = 1;

const getRecords = async () => {
  const url = `https://${KINTONE_DOMAIN}/k/v1/records.json?app=${APP_ID}`;
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': API_TOKEN,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`[${error.code}] ${error.message}`);
  }

  return response.json();
};

curl の場合

curl -X GET \
  "https://your-subdomain.cybozu.com/k/v1/records.json?app=1" \
  -H "X-Cybozu-API-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Python の場合

import requests

KINTONE_DOMAIN = "your-subdomain.cybozu.com"
API_TOKEN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
APP_ID = 1

url = f"https://{KINTONE_DOMAIN}/k/v1/records.json"
headers = {"X-Cybozu-API-Token": API_TOKEN}
params = {"app": APP_ID}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data["records"])

Google Apps Script の場合

function getRecords() {
  const KINTONE_DOMAIN = 'your-subdomain.cybozu.com';
  const API_TOKEN = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
  const APP_ID = 1;

  const url = `https://${KINTONE_DOMAIN}/k/v1/records.json?app=${APP_ID}`;
  const options = {
    method: 'get',
    headers: {
      'X-Cybozu-API-Token': API_TOKEN,
    },
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response.getContentText());
  Logger.log(data.records);
}

複数 API トークンの同時指定

bulkRequest や 複数アプリにまたがる操作を行う場合、1 つのリクエストに複数のアプリの API トークンが必要になることがあります。その場合は、カンマ区切りで複数のトークンを指定します。

const TOKEN_APP_A = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
const TOKEN_APP_B = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

const url = `https://${KINTONE_DOMAIN}/k/v1/bulkRequest.json`;
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'X-Cybozu-API-Token': `${TOKEN_APP_A},${TOKEN_APP_B}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    requests: [
      {
        method: 'POST',
        api: '/k/v1/record.json',
        payload: { app: 1, record: { /* ... */ } },
      },
      {
        method: 'PUT',
        api: '/k/v1/record.json',
        payload: { app: 2, record: { /* ... */ } },
      },
    ],
  }),
});

パスワード認証

パスワード認証は、kintone のログイン名とパスワードを Base64 エンコードして送信する方式です。

const loginName = 'user@example.com';
const password = 'your-password';

// Base64エンコード
const credentials = btoa(`${loginName}:${password}`);

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'X-Cybozu-Authorization': credentials,
  },
});

セッション認証

kintone の JavaScript カスタマイズ内（kintone.api）では、ログインユーザーのセッション情報が自動的に使用されます。これがセッション認証です。

// kintone.api を使う場合、認証ヘッダーは不要
const response = await kintone.api(
  kintone.api.url('/k/v1/records.json', true),
  'GET',
  { app: kintone.app.getId() }
);

セッション認証の特徴:

• 認証ヘッダーの設定が不要
• ログインユーザーのアクセス権限がそのまま適用される
• kintone の画面上で動作するカスタマイズ専用（外部からは使えない）

ゲストスペースの API 呼び出し

ゲストスペース内のアプリに対して API を呼び出す場合、エンドポイントの URL が通常のアプリとは異なります。

// 通常のアプリ
// /k/v1/records.json

// ゲストスペースのアプリ
// /k/guest/{スペースID}/v1/records.json

const GUEST_SPACE_ID = 5;
const APP_ID = 100;

// kintone.api.url の第2引数を true にすると、自動的にゲストスペース対応のURLが生成される
const url = kintone.api.url('/k/v1/records.json', true);

// 外部から呼び出す場合は、URLを手動で構築
const externalUrl = `https://${KINTONE_DOMAIN}/k/guest/${GUEST_SPACE_ID}/v1/records.json`;
const response = await fetch(externalUrl, {
  method: 'GET',
  headers: {
    'X-Cybozu-API-Token': API_TOKEN,
  },
});

セキュリティのベストプラクティス

API トークンの安全な管理

Node.js での環境変数の活用

// .env ファイル（.gitignore に追加すること）
// KINTONE_DOMAIN=your-subdomain.cybozu.com
// KINTONE_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

import 'dotenv/config';

const KINTONE_DOMAIN = process.env.KINTONE_DOMAIN;
const API_TOKEN = process.env.KINTONE_API_TOKEN;

if (!KINTONE_DOMAIN || !API_TOKEN) {
  throw new Error('環境変数 KINTONE_DOMAIN と KINTONE_API_TOKEN を設定してください');
}

kintone.proxy と API トークンの併用

kintone の JavaScript カスタマイズ内から、API トークンを使って別アプリにアクセスする場合は kintone.proxy を使います。これは、ログインユーザーにはアクセス権がないが、API トークンでのみアクセスを許可したいケースに有効です。

(() => {
  'use strict';

  const API_TOKEN = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
  const TARGET_APP_ID = 50;

  /**
   * APIトークンを使って別アプリのレコードを取得する
   * @param { string } query - クエリ
   * @returns { Promise<Record<string, any>[]> }
   */
  const getRecordsWithToken = async (query) => {
    const url = kintone.api.urlForGet(
      '/k/v1/records.json',
      { app: TARGET_APP_ID, query },
      true
    );

    const [body] = await kintone.proxy(url, 'GET', { 'X-Cybozu-API-Token': API_TOKEN }, {});
    const response = JSON.parse(body);
    return response.records;
  };

  kintone.events.on(['app.record.detail.show'], async (event) => {
    const records = await getRecordsWithToken('ステータス in ("公開")');
    console.log('取得結果:', records);
    return event;
  });
})();

まとめ

• kintone REST API の認証方法は API トークン認証、パスワード認証、セッション認証 の 3 種類
• JavaScript カスタマイズ内では kintone.api を使えばセッション認証が自動的に適用される
• 外部サービスからの連携には API トークン認証 を使用し、パスワード認証は避ける
• API トークンはアプリ単位で発行し、最小権限の原則で権限を設定する
• 複数アプリにまたがる操作では、カンマ区切りで複数の API トークンを同時指定できる
• ゲストスペースの API 呼び出しは、エンドポイント URL に /guest/{スペースID}/ を含める
• API トークンは環境変数で管理し、ソースコードにハードコーディングしない

関連記事