Zoom APIは、ミーティング・ユーザー・クラウド録画などのZoomのデータを外部のプログラムから操作するREST APIです。予約が確定したら会議URLを発行して案内メールに載せる、研修の録画を社内の保管先へ移す、といった連携はこのAPIで組みます。この記事では、Server-to-Server OAuthでのトークン取得、Pythonでのミーティング作成、録画の一覧取得とダウンロード、Webhookの URL検証と署名検証までが、この記事でコード付きで整理する対象です。自前で実装するか連携ツールで済ませるかの判断基準も示します。
まとめ:Zoom APIで社内システムと連携するときの認証方式と実装の勘所
自社のZoomアカウントの中だけで動く連携なら、認証はServer-to-Server OAuthを選びます。旧来のJWTアプリは2023年9月に無効化されており、現在は利用できません。他社のZoomアカウントにも配るアプリを作る場合だけ、OAuthアプリにします。
実装で落としやすいのは4か所です。Server-to-Server OAuthではuserIdにmeを使えず、ユーザーIDかメールアドレスを渡す。ミーティング作成はホスト1人あたり1日100回まで。録画の一覧はfromとtoの期間が最大1か月。Webhookは3秒以内に応答し、署名を検証してから処理する。会議と業務データの対応を自社のデータベースで管理する必要があるなら自前実装、通知や転送だけなら連携ツールで足ります。
Zoom APIの全体像と、ベースURL・認証方式・レート制限の前提
Zoom APIはプランごとにレート制限が大きく変わり、一部のAPIにはユーザー単位の1日の上限もあります。設計の前に数字を確かめておけば、本番で429が出てから作り直す事態を避けられます。
ベースURLのapi.zoom.us/v2と、userIdにmeを使えない認証方式
Using Zoom APIsのページによると、既定のベースURLはhttps://api.zoom.us/v2/で、データの所在地に合わせた地域別のURLも用意されています。ユーザーを指定するエンドポイントでは、OAuthアプリならuserIdの代わりにmeと書けます。
ところが同じページには、Server-to-Server OAuthのアプリではmeを使わず、ユーザーIDかメールアドレスを渡す必要があると書かれています。サンプルの/users/me/meetingsをそのまま写して失敗するのは、典型的なつまずきです。業務システム側では、会議を主催させる担当者ごとにZoomのユーザーIDかメールアドレスを持たせておきます。
無料プランはMediumで1日2,000回、プラン別のレート制限と作成上限
各エンドポイントのリファレンスには、Light・Medium・Heavy・Resource-intensiveのいずれかのラベルが付いています。Rate limitsのページに載っている上限を、プラン別に並べると次のとおりです。
| ラベル | Free | Pro | Business以上 |
|---|---|---|---|
| Light | 毎秒4回・1日6,000回 | 毎秒30回 | 毎秒80回 |
| Medium | 毎秒2回・1日2,000回 | 毎秒20回 | 毎秒60回 |
| Heavy | 毎秒1回・1日1,000回 | 毎秒10回 | 毎秒40回 |
| Resource-intensive | 毎分10回・1日30,000回 | 毎分10回 | 毎分20回 |
ProとBusiness以上では、HeavyとResource-intensiveを合わせた1日の上限がそれぞれ30,000回と60,000回です。これとは別に、ミーティングとウェビナーの作成・更新には、ホストのユーザー1人あたり1日100回の上限があり、UTCの0時(日本時間の午前9時)にリセットされます。全社の予約を1人の代表アカウントで主催させる設計にすると、この100回に先に当たります。主催者を担当者ごとに分けるのが前提です。
JWT廃止後に選ぶServer-to-Server OAuthとOAuthアプリ
ZoomのJWTアプリ廃止の告知では、2023年6月1日に新規作成ができなくなり、2023年9月1日にJWTアプリの認可が無効化されると案内されていました。JWTでトークンを作る古いコードは、今から作る連携には使えません。
代わりの選択肢は2つです。自社アカウント内のデータを利用者の操作なしにサーバーから扱うならServer-to-Server OAuth、複数の会社に配る連携アプリならOAuthアプリ。予約システムから自社のZoomを操作する連携の大半は前者で足ります。
Server-to-Server OAuthのアプリ作成からトークン取得までの手順
Server-to-Server OAuthは、アカウントID・クライアントID・クライアントシークレットの3つでアクセストークンを取る方式です。利用者のブラウザでの認可画面が無いので、夜間バッチや予約システムのサーバーから呼ぶ用途に向いています。
Marketplaceでのアプリ作成と、管理者が許可するスコープの絞り込み
アプリはZoom App Marketplaceで「Server-to-Server OAuth」の種類を選んで作り、アプリの詳細ページに表示される3つの認証情報を控えます。開発者がこのアプリを作るには、アカウントの管理者がロールの設定で該当の権限を付けておくことが必要です。Server-to-Server OAuthのページでは、使えるスコープは管理者が認めた範囲に限られ、1つのアプリには1つの連携に必要なスコープだけを付けるよう推奨しています。
この記事のコードで使うのは、ミーティング作成のmeeting:write:meeting:admin、ユーザーの録画一覧のcloud_recording:read:list_user_recordings:admin、会議ごとの録画ファイル取得のcloud_recording:read:list_recording_files:adminです。録画の削除まで自動化する場合だけ、削除のスコープを足します。予約連携のアプリと録画保管のアプリを分けておくと、片方の認証情報が漏れたときの影響範囲を狭められます。
curlでaccount_credentialsのトークンを1時間ごとに取る方法
トークンはhttps://zoom.us/oauth/tokenに、grant_type=account_credentialsとアカウントIDをPOSTして取ります。クライアントIDとシークレットはBasic認証で渡します。
# 認証情報は環境変数から読む(コードやリポジトリに書かない)
curl -s -X POST "https://zoom.us/oauth/token" \
-u "$ZOOM_CLIENT_ID:$ZOOM_CLIENT_SECRET" \
-d "grant_type=account_credentials" \
-d "account_id=$ZOOM_ACCOUNT_ID"
# 返ってきた access_token で、主催者に使うユーザーの情報を確認する
# ZOOM_HOST にはユーザーIDかメールアドレスを入れる(meは使えない)
curl -s -H "Authorization: Bearer $ZOOM_TOKEN" \
"https://api.zoom.us/v2/users/$ZOOM_HOST"
トークンの有効期間は3,600秒(1時間)で、更新トークンはありません。期限が切れたら同じ要求でもう一度取ります。公式ページには、新しいトークンを発行しても以前のトークンは無効にならないと書かれているので、複数のプロセスが別々にトークンを取っても互いを壊しません。それでも呼び出しのたびに取り直すと無駄な往復が増えるため、期限の少し前まではメモリかキャッシュに保持して使い回す作りにします。
Pythonでミーティングを作成し、参加URLを業務システムへ返す実装
予約や研修の登録をきっかけに会議を作り、参加URLを業務データに保存する流れをPythonで書きます。JWT時代のまま更新が止まった第三者のラッパーが多いため、requestsだけで書きます。
ミーティング作成APIの本文とstart_time・timezoneの書き方
Meetings APIのリファレンスの「Create a meeting」に沿うと、本文にはtopic・type・start_time・timezone・duration・settingsを指定します。typeは1が即時、2が日時指定、3が日時なしの定期、8が日時ありの定期です。
import os
import time
import requests
API = "https://api.zoom.us/v2"
_token = {"value": None, "expires_at": 0}
def get_token():
"""Server-to-Server OAuthのトークンを取り、期限の60秒前まで使い回す"""
if _token["value"] and time.time() < _token["expires_at"] - 60:
return _token["value"]
r = requests.post(
"https://zoom.us/oauth/token",
auth=(os.environ["ZOOM_CLIENT_ID"], os.environ["ZOOM_CLIENT_SECRET"]),
data={"grant_type": "account_credentials", "account_id": os.environ["ZOOM_ACCOUNT_ID"]},
timeout=30,
)
r.raise_for_status()
body = r.json()
_token.update(value=body["access_token"], expires_at=time.time() + body["expires_in"])
return _token["value"]
def create_meeting(host_email, topic, start_local, minutes=60):
"""日時指定の会議を作り、業務システムに保存する項目だけを返す"""
payload = {
"topic": topic,
"type": 2,
"start_time": start_local, # 例: "2026-12-01T10:00:00"(末尾にZを付けない)
"timezone": "Asia/Tokyo",
"duration": minutes,
"settings": {"waiting_room": True, "auto_recording": "cloud"},
}
r = requests.post(
f"{API}/users/{host_email}/meetings",
headers={"Authorization": f"Bearer {get_token()}"},
json=payload,
timeout=30,
)
r.raise_for_status() # 成功時は201
m = r.json()
return {"meeting_id": m["id"], "join_url": m["join_url"]}
start_timeの末尾にZを付けるとUTCとして解釈され、timezoneは効きません。日本時間で入力された予約をそのまま渡すなら、Zなしの形式とAsia/Tokyoの組み合わせにします。timezoneを省くとZoomアカウントの既定のタイムゾーンが使われるため、既定が日本時間以外のアカウントでは時刻のずれた会議ができる点に注意が必要です。waiting_roomをtrueにすると、ホストより先に参加できるjoin_before_hostの設定は無効になります。
start_urlの有効期限2時間と、ミーティングIDを64bit整数で持つ注意
作成の応答には、参加者向けのjoin_urlと、ホストが会議を開始するためのstart_urlが含まれます。リファレンスによると、通常のユーザーのstart_urlの有効期限は、発行から2時間です。予約時にstart_urlを保存して当日のメールに載せる設計は、ほぼ確実に失敗します。開始直前に「Get a meeting」を呼び直して最新のstart_urlを取るのが、公式の推奨する方法です。
ミーティングIDは10桁を超えることがあり、リファレンスはlong形式(64bit整数)で保存するよう明記しています。列はBIGINTか文字列にします。またUsing Zoom APIsのページによると、ミーティングIDは最後の利用から30日で期限切れになる場合があり、UUIDは期限切れになりません。業務データにはIDとUUIDの両方を残します。
クラウド録画の一覧取得とdownload_urlからのファイル保存の実装
研修や社内説明会の録画を、Zoomのクラウドから社内のストレージへ定期的に移す処理を組みます。
from・toは最大1か月、next_page_tokenは15分で切れる一覧取得
Meetings APIのリファレンスの「List all recordings」(GET /users/{userId}/recordings)は、Proプラン以上かつクラウド録画が有効なユーザーが前提です。fromとtoはUTCの日付で、期間は最大1か月。指定しないと当日分しか返りません。続きがあれば応答にnext_page_tokenが付き、このトークンは15分で期限が切れます。
def list_recordings(user, date_from, date_to):
"""1か月以内の期間で、ユーザーのクラウド録画を全件取得する"""
params = {"from": date_from, "to": date_to, "page_size": 30}
meetings = []
while True:
r = requests.get(
f"{API}/users/{user}/recordings",
headers={"Authorization": f"Bearer {get_token()}"},
params=params,
timeout=30,
)
if r.status_code == 429:
time.sleep(2) # 秒単位の上限に当たったら少し待って再送する
continue
r.raise_for_status()
body = r.json()
meetings.extend(body.get("meetings", []))
token = body.get("next_page_token")
if not token:
return meetings
params["next_page_token"] = token
3か月分を取り直したいときは、1か月ずつ期間をずらしてこの関数を3回呼びます。next_page_tokenが15分で切れるので、各ページの処理の中でダウンロードまで済ませる作りにすると、大きなファイルの保存中にトークンが失効します。一覧を先に全件取ってから、ダウンロードを別のループで回すのが安全です。
download_access_tokenを付けて録画ファイルを保存する手順
会議ごとの録画ファイルはGET /meetings/{meetingId}/recordingsで取ります。リファレンスによると、include_fields=download_access_tokenを付けると応答にダウンロード用のトークンが入り、各ファイルのdownload_urlにBearerで渡して取得できます。download_urlはリダイレクトを返す場合があるので、取得時にはリダイレクトを追う設定が必要です。
from pathlib import Path
from urllib.parse import quote
def download_meeting_files(meeting_uuid, dest_dir):
"""会議の録画ファイルをすべて保存する"""
# UUIDが「/」で始まるか「//」を含む場合は2回エンコードする
uid = meeting_uuid
if uid.startswith("/") or "//" in uid:
uid = quote(quote(uid, safe=""), safe="")
r = requests.get(
f"{API}/meetings/{uid}/recordings",
headers={"Authorization": f"Bearer {get_token()}"},
params={"include_fields": "download_access_token"},
timeout=30,
)
r.raise_for_status()
body = r.json()
dl_token = body["download_access_token"]
for f in body.get("recording_files", []):
name = f"{f['id']}.{f['file_extension'].lower()}"
with requests.get(f["download_url"], headers={"Authorization": f"Bearer {dl_token}"},
stream=True, allow_redirects=True, timeout=300) as res:
res.raise_for_status()
with open(Path(dest_dir) / name, "wb") as out:
for chunk in res.iter_content(chunk_size=1024 * 1024):
out.write(chunk)
ダウンロード用トークンの取得には、録画の内容を閲覧できる権限が必要です。recording_filesには映像のMP4のほか、音声のM4A、チャット、文字起こしなどが種類別に並ぶので、保管先ではfile_typeごとにフォルダを分けておくと後の検索が楽になります。文字起こしを議事録に回すなら、Zoom標準の文字起こしで足りるかの確認が先です。社内用語の多い会議で精度が足りなければ、AI音声認識システムの開発で専用のモデルを組む選択肢もあります。
Webhookの受信でURL検証・署名検証・3秒応答を満たす実装
録画の完成や会議の終了をきっかけに処理を動かすなら、一覧の定期取得よりWebhookのほうが呼び出し回数を抑えられます。ただしZoomのWebhookは、登録時のURL検証、3秒以内の応答、72時間ごとの再検証という3つの条件を満たさないと止まります。
URL検証のendpoint.url_validationに応答する処理
Using webhooksのページによると、MarketplaceでWebhookの受信URLを登録すると、Zoomはイベント名がendpoint.url_validationのPOSTを送ってきます。本文のpayload.plainTokenを、アプリのシークレットトークンを鍵にHMAC-SHA256で計算して16進数にし、plainTokenとencryptedTokenの2つを持つJSONを3秒以内に200か204で返すと検証が通ります。
同じページは、ZoomのIP範囲はいつでも変わりうるとして、IPアドレスの許可リストより署名の検証を強く推奨しています。
x-zm-signatureの署名検証と録画完成イベントの受け取り
通常のイベントにはx-zm-signatureとx-zm-request-timestampのヘッダーが付きます。v0:{タイムスタンプ}:{本文}という文字列をシークレットトークンでHMAC-SHA256にかけ、先頭にv0=を付けた値が署名と一致すればZoomからの要求です。Flaskで書くと次の形になります。
import hashlib
import hmac
import json
import os
import queue
from flask import Flask, Response, jsonify, request
app = Flask(__name__)
SECRET = os.environ["ZOOM_WEBHOOK_SECRET"].encode()
jobs = queue.Queue()
@app.post("/zoom/webhook")
def receive():
raw = request.get_data() # 署名は受信した本文のバイト列で計算する
ts = request.headers.get("x-zm-request-timestamp", "")
message = b"v0:" + ts.encode() + b":" + raw
expected = "v0=" + hmac.new(SECRET, message, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("x-zm-signature", "")):
return Response(status=401)
event = json.loads(raw)
if event["event"] == "endpoint.url_validation":
plain = event["payload"]["plainToken"]
encrypted = hmac.new(SECRET, plain.encode(), hashlib.sha256).hexdigest()
return jsonify(plainToken=plain, encryptedToken=encrypted)
# 重い処理はキューに渡し、3秒以内に200を返す
jobs.put(event)
return Response(status=200)
公式のNode.jsの例は、受け取った本文をJSONとして読み直してから文字列に戻して署名を計算しています。Pythonで読み直すと空白や文字のエスケープが変わり、署名が一致しなくなることがあるため、ここでは受信したバイト列のまま計算しました。タイムスタンプが現在時刻から大きく離れた要求を捨てる処理も足すと、盗み見た要求の再送にも備えられます。署名検証と冪等な処理の考え方は決済の通知でも同じで、決済Webhookの署名検証と冪等な注文確定の実装で詳しく扱っています。
録画の完成を知らせるrecording.completedイベントにはdownload_tokenが付きます。Meetings Webhooksのリファレンスによると、このトークンは作成から24時間しか使えず、ダウンロードできるのも通知の受信から24時間以内です。キューの処理が週末に止まっていると取りこぼすので、期限切れのときは前章のinclude_fields=download_access_tokenで取り直す経路を用意します。
再送は最大3回、72時間ごとの再検証で6回失敗すると止まる仕様
Using webhooksのページによると、受信側が500番台を返したときなどは、5分後・その20分後・さらに60分後の最大3回だけ再送されます。300番台と400番台は再送されないので、一時的な障害で4xxを返す実装にすると、そのイベントは二度と届きません。処理の失敗はキューの側で扱い、受信の応答は署名が正しければ200に揃えます。
受信URLは72時間ごとに自動で再検証され、2回連続で失敗するとアカウントの所有者に通知メールが届き、6回連続で失敗するとイベントの送信が止まってサブスクリプションが無効になります。間隔が72時間なので、最初の失敗から約15日で止まる計算です。受信サーバーの停止がそのまま連携停止になるため、Webhookだけに頼らず、1日1回は録画の一覧を取り直して差分を拾う処理を併用します。
Zoom APIを自前で実装する条件と、iPaaSや既製連携で足りる場面
ここまでの実装は、トークン・主催者・録画・Webhookの監視を自社で持つことを意味します。すべての連携でそこまでは要りません。
予約・研修・商談の業務データと会議を一体で管理する場合の自前実装
自前実装を選ぶ条件は2つに絞れます。1つは、予約や研修の受講者、商談の顧客といった業務データと会議を1対1で結び、変更やキャンセルを双方向に反映する必要がある場合です。主催者を担当者ごとに振り分けて1日100回の上限を避ける処理や、start_urlを開始直前に取り直す処理は、連携ツールの画面設定では組みにくい部分です。
もう1つは、録画の保管期間や閲覧権限に社内規程があり、誰がいつどの録画を保存・削除したかの記録が要る場合です。監査に耐える記録を自社のデータベースとログに残せるかが決め手になります。予約や基幹のシステム側のAPI設計から含めて検討するなら、API開発・システム連携の範囲で、連携方式と運用監視までまとめて設計できます。
会議URLの通知や録画の転送だけならiPaaSで済ませる判断
反対に、フォームの送信でZoomの会議を1件作ってURLをメールする、録画が完成したらチャットに通知する、といった片方向の連携に受信サーバーを立てるのは過剰です。月の会議数が数十件程度で、失敗しても担当者が気づいて手で作り直せる業務なら、ZapierやMakeなどの連携ツールで十分に回ります。
判断に迷うのは、まず通知だけで始めて後から予約データと同期したくなるケースです。この場合も、連携ツールで業務の流れを固めてから、件数と要件が増えた時点で自前実装に移すのが無駄の少ない順序です。連携ツールの選定と設定はiPaaS導入支援(Zapier/Make/Workato/Yoom)で相談できます。同じ考え方で組んだ他のSaaSの例として、Asana APIの認証とタスク作成・Webhook連携の実装も参考になります。
Zoom APIのよくある質問:無料プラン・JWT・userId・録画の扱い
Zoom APIを使い始める前によく調べられる疑問を5つ取り上げます。
Zoom APIは無料プランでも使えますか?
使えます。公式のRate limitsのページには無料プランの上限が載っており、たとえばMediumのAPIは毎秒2回・1日2,000回までです。ただし1日の枠が小さく、全件を毎回取り直す同期はすぐ上限に届きます。クラウド録画の一覧取得はProプラン以上が前提なので、録画を取り出す連携は無料プランでは組めません。
JWTアプリで作ったZoomの連携はまだ動きますか?
動きません。Zoomの告知では、2023年9月1日にJWTアプリの認可が無効化されると案内されていました。古い連携を引き継いだ場合は、自社アカウント内の処理ならServer-to-Server OAuthへ、他社にも配るアプリならOAuthアプリへ作り直します。認証の差し替えに加えて、スコープの指定とmeが使えない点への対応も要ります。
Server-to-Server OAuthでusers/meを指定するとエラーになるのはなぜですか?
公式のUsing Zoom APIsのページに、Server-to-Server OAuthのアプリではmeを使わず、ユーザーIDかメールアドレスを渡す必要があると書かれているためです。この方式のトークンはアカウント全体の権限で動くため、「自分」にあたるユーザーが決まりません。主催させたいユーザーのIDかメールアドレスをuserIdの位置に入れれば動きます。
Zoom APIで会議の作成が429になるのはなぜですか?
秒単位の上限に当たっているか、ホスト1人あたり1日100回の作成・更新の上限に当たっているかのどちらかです。後者はUTCの0時、日本時間の午前9時にリセットされるまで解消しません。全社の会議を1つの代表アカウントで主催させていると起きやすいので、担当者ごとに主催者を分けます。秒単位の上限なら、少し待ってからの再送で要求を通すことが可能です。1日の上限に当たったときは、応答ヘッダーで次に再試行できる時刻を確認するよう公式が案内しています。
Zoomの録画を自動で社内ストレージに保存するにはどうすればよいですか?
recording.completedのWebhookを受けて、付いてくるdownload_tokenでdownload_urlからファイルを取るのが基本の流れです。このトークンは24時間しか使えないため、取りこぼしに備えて1日1回GET /users/{userId}/recordingsで一覧を取り直し、未保存の録画をdownload_access_tokenで取得する処理を併用します。録画の保存先や文字起こしの使い方は、会議ツール別のAI議事録の使い分けも参考にしてください。
関連記事
- Asana APIの使い方:PAT・OAuthの認証とタスク作成・Webhook連携の実装【2026年11月】:同じ業務SaaSのAPI連携と、Webhookのハンドシェイクの実装例
- Backlog APIの使い方|APIキー・OAuth2の認証と課題登録・Webhook連携の実装【2026年11月】:課題管理とつなぐ場合のAPI連携の実装例
- Slack APIとは?できること・無料の範囲とアプリ作成からBolt実装までの使い方:会議URLや録画の完成をチャットに通知する側のAPI
- AI議事録・自動文字起こしとは?仕組み・精度・法人での選び方【2026年版】:取り出した録画を議事録にする仕組みと選び方
- 決済Webhookとは?仕組み・主要イベントと署名検証・冪等な注文確定の実装を開発視点で解説:Webhookの署名検証と冪等な処理の別の例