API トークン

スクリプトや AI エージェント用のトークンを作成する

作成できるユーザー
トークンを作成する
自分のトークン

作成できるユーザー

有効期間の長いトークンを使うと、スクリプトはパスワードなしで API を呼び出せます。7.3.0 以降、作成には allowApiTokens ロールオプションが必要です。

roles:
  - name: automation
    groups:
      - local/automation
    options:
      allowApiTokens: true
      extendedTokenExpiration: true   # also tokens that never expire

7.2.0 までは、このオプションは extendedTokenExpiration だけでした。7.3.0 より前のロールでこのオプションだけを設定しているものには allowApiTokens が付与されるため、既存のトークンはそのまま使えます。両方を設定すると、期限のないトークンも作成できます。ロールオプションを参照してください。

トークンを作成する

プロフィール > API トークン のタイトル行にある 新しいトークン をクリックすると、3 ステップのウィザードが開きます。

詳細: 一覧でトークンを見分けるための名前と、有効期間を指定します。選択肢は 30、90、180、 365 日のうち API_TOKEN_MAX_DAYS (既定は 90) までのもの、その上限値そのもの、そして extendedTokenExpiration がある場合は 期限なし です。スクリプトに必要な最短の期間を選んでください。
確認: ローカルまたは LDAP のアカウントはパスワードを入力します。パスワードはトークンには保存されません。Microsoft Entra ID や OIDC のアカウントはここではパスワードがありません。トークンはセッションから作成され、そのセッションは 10 分以内にサインインしたものである必要があるため、先にプロバイダーから再サインインを求められることがあります。
コピー: トークンが表示されます。表示されるのは 一度だけ です。 コピー でコピーし、パスワードと同じように安全に保管してください。

API を呼び出すたびに、トークンを Authorization ヘッダーで送ります。

curl -H "Authorization: Bearer $TOKEN" https://af.example.com/api/v2/job

API トークンから別のトークンを作成することはできません。SSO アカウントのトークンには、最後にサインインしたときのロールが含まれます。ID プロバイダー側でグループを変更しても、再度サインインして新しいトークンを作成するまでは反映されません。

自分のトークン

作成したトークンは、名前、作成日時、有効期限、最終使用日時とともに一覧に表示されます。行のメニューにある 取り消す でトークンを無効にできます。管理者も 設定 > ユーザー のあなたのページでトークンを確認し、取り消すことができます。トークンは有効期限で終了するほか、次の場合にはそれより早く終了します。

一覧からの 取り消し
トークンを使ったログアウト ( Authorization ヘッダーにトークンを付けた POST /api/v2/auth/logout )。トークンが作成されたセッションとともに終了します。
パスワードの変更。それ以前に作成されたアカウントのすべてのトークンとセッションが終了します。アカウントのブロックも同様です。

期限のないトークンも、これらの場合には終了します。スクリプトはログイン API とその expiryDays パラメーターを使って、自分でトークンを要求することもできます ( POST /api/v2/auth/login?expiryDays=90 または expiryDays=never )。 API_TOKEN_MAX_DAYS より長い expiryDays はその値に切り詰められます。