LINE WORKS API 2.0 の認証を通すまで

LINE WORKS API を使うとき、最初の関門が認証です。ドキュメントが API 1.0 と 2.0 で分かれており、検索で出てくる情報も混在しています。ここでは 2.0 の Service Account 認証に絞って、アクセストークンを取得するまでを整理します。

サーバー側の処理から Bot を動かしたり、メンバー情報を取得したりする用途はこの方式になります。画面上でユーザーに許可を求める必要がありません。

用意する4つの情報

すべて Developer Console のアプリ設定から取得します。

Private Key は再ダウンロードできません。取得した時点で、パスワードマネージャや Secret Manager に保管しておきます。

JWT を組み立てる

Service Account 認証では、まず JWT を自前で作り、それをアクセストークンと交換します。

署名アルゴリズムは RS256です。Private Key で署名します。

import jwt
import time

now = int(time.time())
assertion = jwt.encode(
    {
        "iss": CLIENT_ID,
        "sub": SERVICE_ACCOUNT,
        "iat": now,
        "exp": now + 3600,
    },
    PRIVATE_KEY,
    algorithm="RS256",
)

exp を長く取りすぎると弾かれます。1時間以内に収めます。

アクセストークンと交換する

作った JWT をトークンエンドポイントに POST します。

import requests

res = requests.post(
    "https://auth.worksmobile.com/oauth2/v2.0/token",
    data={
        "assertion": assertion,
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "bot",
    },
)
access_token = res.json()["access_token"]

scope には使う機能を指定します。Bot からメッセージを送るだけなら botです。メンバー情報を読むなら user.read を追加するなど、必要な分だけを指定します。Developer Console 側のアプリにも同じ権限を付与しておかないと、トークンは取れてもAPI呼び出しで弾かれます。

トークンの寿命を前提に設計する

毎回 JWT から取り直しても動きますが、呼び出し回数が増えるとレート制限に当たります。取得したトークンをキャッシュし、期限切れが近づいたらリフレッシュトークンで更新する構成にしておきます。

定期実行のバッチであれば、Secret Manager などにトークンを保存し、有効期限を一緒に持たせるのが扱いやすいです。

つまずきやすい箇所

• invalid_client が返る：Client Secret の前後に空白が混ざっているケースが多いです
• invalid_grant が返る：iss と sub の取り違えです。iss が Client ID、sub が Service Account
• トークンは取れるが 403：Developer Console 側でアプリに権限を付けていません
• Private Key の改行：環境変数に入れるときに改行が \n の文字列になっていると署名できません

まとめ

• 必要な情報は Client ID / Client Secret / Service Account / Private Key の4点
• JWT は RS256、exp は1時間以内
• scope は必要最小限にし、Developer Console 側の権限と揃えます
• アクセストークンは24時間です。キャッシュ前提で設計します