Transloadit
料金
  • ファイルアップロード
  • ファイルインポート
  • バッチ処理
  • 動画エンコーディング
  • 音声エンコーディング
  • 画像処理
  • ドキュメント処理
  • 人工知能
  • ファイルフィルタリングとセキュリティ
  • メディアカタログ化
  • ファイル圧縮
  • コード評価
  • ファイルエクスポート
  • Smart CDN
  • すべてのサービスを表示
  • 連携機能を見る
  • 実行可能なデモを試す (English)
  • Uppy
  • TransloaditKit
  • Android 用 SDK
  • Node.js 用 SDK
  • Next.js 用ビューアー
  • Python 用 SDK
  • Ruby 用 SDK
  • Go 用 SDK
  • Java 用 SDK
  • PHP 用 SDK
  • Zapier
  • MCP サーバー
  • Transloadit CLI
  • Terraform
  • 基本事項
  • ベストプラクティス
  • よくある質問
  • Robot
  • API
  • 形式
  • 初めてのアプリ開発
  • 会社概要
  • 比較
  • オープンソース
  • お客様の声
  • 採用情報 (English)
  • セキュリティ
  • 記事
  • 開発者ニュース (English)
  • 開発のヒント
  • プレス
  • 研究 (English)
  • 導入事例
  • ソリューション
  • ガイド (English)
  • 用語集
  • 法務 (English)
  • ツール
  • 世界中の数百万人に教育を届ける Coursera を支援
  • Transloadit サポート
  • オープンソースサポート
  • サービスレベル契約 (English)
  • エンジニアによるデモを予約 (English)
基本事項Robotよくある質問API形式ベストプラクティス
トピック
  • エンドポイント
  • レスポンスコード
  • 認証
  • ウェブフック
  • メタデータ
  • API のセキュリティ
  • レート制限
  • キュー
  • 再開可能なアップロード
認証
  • Bearer トークンを作成する
  • 新しい Auth Key を作成する
  • Auth Keys の一覧を取得する
  • Auth Key のスコープを取得する
  • Auth Key を編集する
  • Auth Key を削除する
  • Auth Key のシークレットを取得する
Assemblies
  • 新しい Assembly を作成する
  • Assembly Status を取得する
  • 指定された ID で Assembly を作成する
  • Assembly の変更をリアルタイムでストリーミングする
  • 実行中の Assembly をキャンセルする
  • Assembly を再実行する
  • Assemblies の一覧を取得する
  • Assembly Status レスポンス
  • Assembly の統計情報を取得する
ウェブフック
  • Assembly Notifications を取得する
  • Assembly Notification を再送する
請求
  • 対象月の請求書を取得する
キュー
  • 現在使用中の Priority Job Slots を取得する
  • Priority Job Slots の統計を取得する
再開可能なアップロード
  • tus の機能を確認する
  • tus アップロードを作成する
  • tus アップロードのオフセットを取得する
  • tus ファイルのバイト列をアップロードする
  • tus アップロードを終了する
  • tus アップロードをダウンロードする
Template 認証情報
  • 新しい Template 認証情報を作成する
  • Template 認証情報を取得する
  • Template 認証情報を編集する
  • Template 認証情報を削除する
  • Template 認証情報の一覧を取得する
  • Template 認証情報の種類を取得する
Templates
  • 新しい Template を作成する
  • Template を取得する
  • Template を編集する
  • Template を削除する
  • Templates の一覧を取得する
  • Cron Template の実行履歴を取得する alpha
デジタルアセット管理
  • DAM アセットを移動するか、名前を変更する alpha
  • DAM アセットを削除 alpha
  • DAM アセットを一括移動する alpha
  • DAM アセットを一括削除する alpha
  • ストレージ内のファイルまたはフォルダーを移動 alpha
  • ストレージ内のアセットを取得
  • ストレージ内のアセットを一覧表示

認証

Auth Keys

Auth Key で認証するマルチパートの Assembly 作成リクエストでは、JSON エンコードされた params フォームフィールド内に auth オブジェクトを含めます。このような params の最小の値を以下に示します。

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  }
}

key フィールドは、Transloadit Workspace に関連付けられた Auth Key を指し、認証情報ページで確認できます。上記は、Auth Key を使用する Assembly リクエストの最小の認証オブジェクトです。他のエンドポイントや認証方式では、それぞれのエンドポイントのドキュメントや以下の説明に記載されているように、異なるリクエスト形式を使用する場合があります。

/transloadit/import を直接、または Template を通じて使用する Assemblies には、Bearer トークン、または将来の params.auth.expires タイムスタンプを含む署名済みの params のいずれかが必要です。これは、Workspace の Signature Authentication が無効になっている場合にも適用されます。Auth Key だけでは不十分です。Bearer 認証を使用するリクエストには、別途 Signature や有効期限を指定する必要はありません。公開ストレージ用の Builtin Templates は例外で、すべてのストレージインポートが宣言された公開プレフィックス内に収まる場合に限り、署名されていないリクエストに対応できます。これによって、任意の Steps を含む署名されていない Assemblies や、非公開のストレージパスへのアクセスが許可されるわけではありません。

Signature Authentication

アカウントで Signature Authentication を有効にすることをお勧めします。特に、信頼できない環境から Transloadit と連携する場合(Uppy⁠ を使用してブラウザーから連携する場合など)は、有効にすることをお勧めします。Signature Authentication は、Workspace 設定から有効にできます。

警告

API と連携する際には、Signature Authentication を有効にすることを_強くお勧めします_。特に、ユーザーが Auth Key にアクセスできる可能性がある、信頼できない環境では重要です。

Signature Authentication を有効にすると、Workspace の Auth Secret(認証情報ページの Auth Key の隣に表示されます)が、シリアライズされた params 値の正確なバイト列から生成される HMAC のキーとして使用されます。この値には、key(前述の Auth Key)と、リクエストの有効期限として使用される近い将来のタイムスタンプである expires パラメーターの両方が含まれます。

Transloadit で Assemblies を作成する際、バックエンドで、正当な使用とみなされる特定のパラメーター、認証済みユーザー、および時間枠だけを対象とする Signature を計算できます。たとえば、ログインしていないユーザーに対しては Signature の生成を拒否するようにします。サーバー側で任意のビジネスロジックを使用して、Signature を発行するかどうかを判断できます。Transloadit では、Auth Key で認証する API リクエストについて、ペイロードに対する正しい Signature を必須にできます。

Auth Key で認証する API リクエストで Signature Authentication を必須にするには、次の操作を行います。

  1. アカウントの Workspace 設定に移動します。
  2. API 設定セクションで、正しい Signature を必須にするオプションを有効にします。
  3. 自動保存が完了するまで待ちます。

有効な Bearer トークンは、Workspace と Template の設定を含め、Signature の要件をバイパスします。トークンのスコープとオーディエンスの制限は引き続き適用されます。これらの設定は、Assembly のステータス、キャンセル、再開可能なアップロードの URL など、ケイパビリティに基づくアクセスに認証を追加するものではありません。Assembly IDs とケイパビリティ URL は非公開にし、各エンドポイントの認証ガイダンスに従ってください。

補足

ほとんどのバックエンド SDK は、Auth Secret を指定すると、自動的に Signature Authentication を使用します。そのため、この導入部分を読むだけで十分かもしれません。ただし、ブラウザー(Uppy など)のような信頼できない環境に Transloadit を組み込む場合は、引き続き読み進めて、バックエンドからその環境に Signatures を提供する方法を確認してください。

Signatures の生成方法

では、具体的にはどのようになるのでしょうか。

Signature Authentication を使用せずに Assembly を作成する場合、一般的な params フィールドは次のようになります。

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  },
  "steps": {
    // …
  }
}

この例の auth.key は、アカウントの API 認証情報にある Auth Key です。

このリクエストに署名するには、auth.expires フィールドを追加する必要があります。これにより、Signature で保護されるペイロードにこのフィールドが含まれます。誰かがこの値を変更すると、Signature が一致しなくなるため、Transloadit はリクエストを拒否します。署名したペイロードと、受信したペイロードが異なるためです。Signature が一致する場合は、指定されたとおりに日時を比較し、必要に応じて拒否します。これにより、このペイロードを入手した第三者がリクエストを無期限に繰り返すことは非常に困難になります。A+ 評価の HTTPS によって、このような行為の防止にはすでに大きな効果が期待できますが、ブラウザーのキャッシュはそれよりものぞき見されやすい可能性があるためです。

expires プロパティには、(近い)将来のタイムスタンプを含める必要があります。日付には ISO 8601 形式(YYYY-MM-DDTHH:mm:ss.sssZ)を使用し、タイムゾーンには必ず UTC を使用してください。例:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211",
    "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP"
  },
  "steps": {
    // …
  }
}

このリクエストの Signature を計算するには、次の手順を実行します。

  1. フロントエンドで、上記の JavaScript オブジェクトを JSON 文字列に変換し、バックエンドに送信します。
  2. バックエンドで、Auth Secret をキーとし、Auth Key の signature_algo に設定されたアルゴリズムを使用して、この文字列に対する RFC 6234 準拠⁠の HMAC の 16 進数表現の Signature を計算します。新しい Auth Keys のデフォルトは sha384 です。アルゴリズムが設定されていない従来の Auth Keys は、sha384、sha256、または sha1 を受け付けます。signature 文字列の先頭に、小文字のアルゴリズム名を付けます。たとえば、デフォルトのアルゴリズムでは sha384:<HMAC-signature> を使用します。この文字列をフロントエンドに送信できます(ただし、フロントエンドからの正当なリクエストであることを保証するための適切なチェックを行っていることが前提です)。
  3. フロントエンドで、この値を含む signature マルチパート POST フィールドをリクエストに追加します(HTML フォームの隠しフィールドを使用するなど)。
補足

実装で steps の代わりに template_id を使用している場合、Template に含まれる Instructions に対して Signature を生成する必要はありません。署名するのは通信ペイロードだけにすべきです。

補足

リクエストごとに、ランダムに生成した params.nonce 値を params のトップレベルに含めることを強くお勧めします。これにより、個別に生成された Signatures がそれぞれ異なるものとなり、意図しない Signature の再利用を防げます。nonce によって再試行が冪等になるわけではありません。Assembly 作成リクエストを再試行すると、別の Assembly が作成される可能性があります。必要に応じて、アプリケーション内で再試行の重複排除を処理してください。署名済みの params を異なるエンドポイント間で再利用しないでください。Template の読み取り、Auth Key の一覧取得、Template 認証情報の一覧取得、請求情報の読み取りでは、別のエンドポイント用としてすでに記録された、または Assembly の作成に使用された Signatures を SIGNATURE_REUSE_DETECTED で拒否します。リクエストごとに、新しい署名済み params を生成してください。

リクエスト全体は、次のようになります。

{
  "params": {
    "auth": {
      "key": "23c96d084c744219a2ce156772ec3211",
      "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP",
    },
    "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
    "steps": {
      // …
    },
  },
  "signature": "sha384:YOUR_SIGNATURE",
}

Transloadit がリクエストを受信すると、同じ手順で Signature を生成し、2 つの Signatures を比較します。Signatures が異なる場合、サーバーは INVALID_SIGNATURE を返します。

手順をまとめると、次のようになります。

  1. params フィールドとして Transloadit に送信する JSON ペイロードを生成します。
  2. Auth Secret をキーとして使用し、ペイロードの内容に基づいて Signature を計算します。
  3. signature フィールドに Signature を渡して、Transloadit にリクエストを送信します。
  4. Transloadit は、アカウントの Auth Secret とペイロードの内容を使用して、同じ Signature を計算します。
  5. Signatures が一致する場合、リクエストが許可され、適切なレスポンスが送信されます。一致しない場合、リクエストは拒否され、コード INVALID_SIGNATURE のエラーが返されます。

これにより、Transloadit は呼び出し元を認証し、params の完全性を検証できます。第三者は、Auth Secret にアクセスできなければ、一致する Signature を計算できないためです。TLS は、クライアントに対して Transloadit を認証し、接続を保護します。Webhook の署名は、Transloadit からサーバーに送信されるリクエストのための別のフローです。

以下に、Assembly を作成する POST リクエストの例をいくつか示します。Signature の生成を自動的に処理し、十分にテストされている SDK のいずれかを使用することを強くお勧めします。

補足

Webhook の署名方法は、API リクエストとは異なります。Transloadit は、HMAC-SHA1 と該当する Auth Secret を使用して、transloadit フォームフィールド内の JSON 文字列の正確なバイト列に署名します。signature フィールドには、アルゴリズムのプレフィックスを含まない 16 進数のダイジェストが格納されます。以下の API リクエストの署名例を使用するのではなく、Auth Secret の選択方法も含め、Webhook の検証手順に従ってください。

各言語のコード例

以下の例では、公式 SDK を使用して Assemblies を作成する方法を示します。SDK はすべての Signature の生成を内部で処理するため、より簡単かつ安全に連携できます。

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const response = await transloadit.createAssembly({
  params: {
    template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
    // your other params like notify_url, fields, etc.
  },
  waitForCompletion: true,
})

console.log(response)

Signature を個別に計算する必要がある場合(フロントエンドで使用する場合など)は、calcSignature を使用できます。

const { signature, params } = transloadit.calcSignature({
  template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})

console.log(signature, params)

Signature の実装のソースコードを見る⁠

補足

Signature の具体的な実装の詳細を確認したい場合(SDK が提供されていない言語で署名を実装する場合など)は、上記のソースコードのリンクを参照してください。Signature は、Auth Secret をキーとし、Auth Key の signature_algo に設定されたアルゴリズムを使用して、JSON エンコードされた params 文字列に対して計算される、RFC 6234 準拠⁠の HMAC の 16 進数ダイジェストです。新しい Auth Keys のデフォルトは sha384 です。Signature の先頭に、小文字のアルゴリズム名を付けてください(例:sha384:...)。

curl --fail-with-body -sS --location 'https://api2.transloadit.com/assemblies' \
  --form 'params={"auth":{"key":"23c96d084c744219a2ce156772ec3211","expires":"YOUR_FUTURE_ISO_8601_TIMESTAMP"},"template_id":"9cf67cbba601e37ee10c442b037e0"}' \
  --form 'signature=sha384:YOUR_SIGNATURE' \
  --form 'files=@/path/to/your/file.jpg'

Smart CDN の署名付き URL

Smart CDN URL に署名するには、通常の API の Signatures と同様の手順を使用します。Auth Secret をキーとして、Smart CDN URL から導出される文字列に対して HMAC ダイジェストを計算します。Signature が有効であるためには、使用する Auth Key で Smart CDN の使用が有効になっている必要があります。

重要

署名付き Smart CDN URL を生成するには、認証情報ページにある、Smart CDN 用として指定された Auth Key を使用してください。Smart CDN URLs には sha256 が必要です。通常の API リクエストの Signatures では、Auth Key の signature_algo に設定されたアルゴリズムを使用します。新しい Auth Keys のデフォルトは sha384 です。

補足

s= と expires= に基づく従来の Smart CDN の Signatures は非推奨です。新しい連携では、必ず sig= と exp= を使用してください。

Smart CDN の Signature の生成は、バックエンドで行う必要があります。この処理では Auth Secret を使用します。これは機密情報であり、フロントエンドでユーザーに公開してはいけません。

一般的な Smart CDN URL は、次の構造になっています。

https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]
  • [your-workspace] は Transloadit Workspace の名前です
  • [template-name] は Template の名前です
  • [file-path] は変換するファイルへのパスです
  • [parameters] は指定する変換パラメーターです(例:h=100)

署名付き Smart CDN URL は、次の手順で生成します。

  1. exp クエリパラメーターを追加し、それ以降は Smart CDN が Signature を受け付けなくなる将来の時刻を定義します。これは、ファイルへのアクセスを時間的に制限するのに役立ちます。有効期限は、UNIX エポック(UTC の 1970 年 1 月 1 日の開始時点の午前 0 時)からのミリ秒数で表します。このパラメーターは任意ですが、常に有効期限を設定することを強くお勧めします。たとえば、exp=1722517200000 を使用する Signature は、2024 年 8 月 01 日(木)13:00:00 GMT まで有効です。
  2. auth_key クエリパラメーターを追加し、Signature の作成に使用する Auth Secret に対応する Auth Key を定義します。このパラメーターが設定されていない場合、Transloadit の API は、Smart CDN が有効になっている最も古い Auth Key のペアが Signature に使用されたとみなします。auth_key パラメーターを設定すると、ユーザーの利用を中断することなく Auth Key をローテーションできるため、設定することを強くお勧めします。例:auth_key=23c96d084c744219a2ce156772ec3211
  3. URLSearchParams.sort() と同じように、UTF-16 コードユニットを使用して、クエリパラメーターをキーの昇順で並べ替えます。ソートは安定ソートである必要があります。つまり、クエリ文字列に同じキーが複数回出現する場合、対応する値の相対的な順序を維持する必要があります。たとえば、h=100&f=png&f=jpg&auth_key=hello&exp=123 は auth_key=hello&exp=123&f=png&f=jpg&h=100 に並べ替えられます。
  4. 次の値を連結して、署名対象の文字列を構築します。
    [your-workspace]/[template-name]/[file-path]?[sorted-parameters]
    
    [your-workspace]、[template-name]、[file-path] の値は、URL で安全に使用できる文字だけが含まれるよう、URL エンコードする必要があります。この文字列の先頭にはスラッシュを付けない点に注意してください。[sorted-parameters] が空の場合、? 文字は省略する必要があります。
  5. Auth Secret をキーとし、SHA256 をハッシュアルゴリズムとして、署名対象の文字列に対する RFC 6234 準拠⁠の HMAC の 16 進数表現の Signature を計算します。16 進数表現の Signature の先頭に、小文字のアルゴリズム名とコロン、つまり sha256: を付けます。たとえば、SHA256 の場合は sha256:[hmac-signature] を使用します。
  6. プレフィックス付きの 16 進数表現の Signature を、sig クエリパラメーターとして URL に追加し、署名付き Smart CDN URL を作成します。
    https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature]
    
    [your-workspace]、[template-name]、[file-path] の値は、URL で安全に使用できる文字だけが含まれるよう、URL エンコードする必要があります。この署名付き URL は、有効期限に達するまでフロントエンドに送信したり、フロントエンドで使用したりできます。

セキュリティとキャッシュの有効期間

署名付き Smart CDN URLs は、アクセス制御の仕組みであるだけではありません。その有効期限は、新しく生成された結果をどのくらいの期間キャッシュ可能にするかも決定します。

  • exp を短くすると、リプレイ可能な期間が短くなり、アクセス制御が厳しくなります。
  • exp を長くすると、キャッシュの再利用が増え、オリジン側の処理が減り、通常はレイテンシとエンコード量が低減します。
  • 実際には、署名付き Smart CDN レスポンスの実効的なキャッシュ有効期間は、Signature の残りの有効期間によって制限されます。

つまり、トレードオフは明確です。

  • セキュリティをより重視する場合:短い exp を使用します。これは、実効的なキャッシュ TTL も短くなることを意味します。
  • キャッシュの再利用とコスト削減をより重視する場合:長い exp を使用します。これは、URL をより長期間使用できることも意味します。

コンテンツの機密性と、どの程度キャッシュを再利用したいかに応じて、有効期間を選択してください。多くの画像やプレビューのユースケースでは、適度な有効期間によって良好なバランスが得られます。機密性が非常に高いコンテンツには、はるかに短い有効期間を使用してください。

コード例

以下に、SDK を使用して署名付き Smart CDN URLs を生成する、各言語の例を示します。

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const url = transloadit.getSignedSmartCDNUrl({
  workspace: 'YOUR_WORKSPACE',
  template: 'YOUR_TEMPLATE',
  input: 'image.png',
  urlParams: { height: 100, width: 100 },
})

console.log(url)

解約後の読み取りアクセス

解約済みの Workspaces では、新しい Bearer トークンを作成できません。解約後のアクセスを明示的に許可するエンドポイントには、この手順へのリンクがあります。既存の有効な Auth Key とその Auth Secret を使用してください。そのキーは、エンドポイントに記載されているスコープを引き続き付与している必要があります。これによって書き込みアクセスが復元されたり、解約後に他のエンドポイントが利用可能になったりするわけではありません。

信頼できるサーバー側の Node.js プロジェクトで、yarn add @transloadit/node を使用して SDK をインストールします。TRANSLOADIT_KEY と TRANSLOADIT_SECRET を設定し、次に TRANSLOADIT_URL を、エンドポイントのページに記載されている完全な HTTPS URL に設定します。パスパラメーターがある場合は、リソースの値に置き換えてください。両方の認証情報、署名付き URL、およびレスポンスは非公開にしてください。この構成をブラウザーのコードで実行してはいけません。

SDK は、新しい Auth Keys のデフォルトである sha384 で params に署名し、有効期限を指定します。この例では、Signature の再利用を避けるために、新しい nonce を追加しています。キーが別の署名アルゴリズムを使用している場合は、calcSignature の第 2 引数としてそのアルゴリズムを渡してください。エンドポイントのフィルターは、第 1 引数として渡すオブジェクト内に、nonce と一緒に指定します。この手順では、SDK は /token を呼び出しません。

これを read-api.mjs として保存し、node read-api.mjs を実行します。

import { randomUUID } from 'node:crypto'

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_URL } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_URL) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_URL')
}
const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})
const { params, signature } = transloadit.calcSignature({ nonce: randomUUID() })
const url = new URL(TRANSLOADIT_URL)
url.searchParams.set('params', params)
url.searchParams.set('signature', signature)
const response = await fetch(url, { redirect: 'error' })
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const result = await response.json()
if (result.error) throw new Error(result.error)
console.log(JSON.stringify(result, null, 2))

URL による MCP クライアントの接続

ChatGPT、Codex、Claude.ai、Claude Desktop、Claude Code、Cursor などのエージェントクライアントは、https://api2.transloadit.com/mcp でホストされている MCP サーバーに、その URL だけで接続できます。Transloadit API は、そのための OAuth 2.1 認可サーバーです。クライアントはエンドポイントを検出し、自身を識別し、ログインと同意のためにユーザーをコンソールに誘導し、最終的に mcp オーディエンス用の短寿命の Bearer トークンとリフレッシュトークンを取得します。Auth Secret がアカウントの外に出ることはありません。

  1. 検出。 MCP サーバーは、認証されていないリクエストに対して 401 と WWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp" ヘッダーを返します。この RFC 9728⁠ ドキュメントは、https://api2.transloadit.com を認可サーバーとして指定しています。その認可サーバーの https://api2.transloadit.com/.well-known/oauth-authorization-server にある RFC 8414⁠ メタデータには、以下のエンドポイントが記載されています。
  2. クライアントの識別。 次のいずれかを行います。Client ID Metadata Document⁠ を提示します。これは、client_id そのものである HTTPS URL で、同じ client_id、client_name、および redirect_uris を含む JSON を配信します。または、https://api2.transloadit.com/oauth/register で RFC 7591⁠ の動的クライアント登録を使用して、一度登録します。クライアントは、client_id だけを送信する(token_endpoint_auth_method: "none"。省略時も同様)、クライアントシークレットで認証する(client_secret_basic または client_secret_post)、または private_key_jwt と jwks_uri で認証する、のいずれかを行います。レスポンスには不透明な client_id が含まれ、シークレットを使用する方式では、そのレスポンスでのみ表示される client_secret も含まれます。リダイレクト URI は、完全一致する HTTPS URL、または任意のポートで一致するループバックの http://localhost / http://127.0.0.1 URL である必要があります。シークレットを使用して登録されたクライアントは、すべてのトークンリクエストと失効リクエストで、HTTP Basic を使用するか、フォーム内の client_id と client_secret として、シークレットを送信します。その他のトークンリクエストでは、クライアントのドキュメントに記載されている方式(token_endpoint_auth_methods_supported、またはそれがなければ token_endpoint_auth_method)、あるいは登録時に宣言された方式に従い、none または private_key_jwt でクライアントを認証します。最初のトークンリクエストによって、そのグラントは使用された方式に関連付けられます。あるグラントのリクエストに RFC 7523⁠ の client_assertion が含まれた場合、その後のそのグラントに対するすべてのトークンリクエストと失効リクエストにも、これを含める必要があります。このアサーションは、クライアントの jwks_uri にあるキーで署名された(RS256 または ES256)JWT であり、iss と sub はクライアント ID です。aud は、このデプロイメント用に設定されたトークンエンドポイントの URL またはそのオリジン(末尾のスラッシュなし)です。exp は 5 分以内であり、jti は、アサーションが有効な間、クライアントごと、リージョンごとに 1 回だけ受け付けられます。リクエストごとに新しい jti を使用してください。
  3. 同意。 クライアントは、response_type=code、自身の client_id、redirect_uri、PKCE の code_challenge(S256 のみ)、任意の scope と state、および resource=https://api2.transloadit.com/mcp を指定して、https://transloadit.com/c/oauth/authorize を開きます。ログインして Workspace を選択し、承認すると、コンソールは code、指定した state、および iss=https://api2.transloadit.com を付けてブラウザーをリダイレクトして戻します。このコードは、クライアント、リダイレクト URI、チャレンジ、および Workspace に関連付けられ、120 秒後に失効します。
  4. トークン。 クライアントは、grant_type=authorization_code を code、code_verifier、client_id、および redirect_uri とともに https://api2.transloadit.com/token に POST し、access_token(デフォルトで 604,800 秒、7 日間有効)、その scope、および refresh_token を受け取ります。grant_type=refresh_token を refresh_token と client_id とともに POST すると、新しいペアが返され、提示されたリフレッシュトークンは使用済みになります。リフレッシュトークンの有効期間は 30 日間であり、使用済みのものを再利用すると、その系列全体が失効します。クライアントシークレットで認証するクライアントには、代わりに同じリフレッシュトークンが返され、そのリフレッシュ時点からさらに 30 日間有効になります。
  5. 失効。 RFC 7009⁠ に従い、token(アクセストークンまたはリフレッシュトークン)を https://api2.transloadit.com/oauth/revoke に POST するか、コンソールで接続を取り消します。

resource インジケーター(RFC 8707⁠)は、トークンの用途を決定します。resource=https://api2.transloadit.com/mcp(省略時のデフォルト)は、MCP サーバーだけが受け付ける mcp トークンを発行します。このトークンには、最大でも安全な MCP スコープ(assemblies:write、assemblies:read、templates:read)だけが含まれ、Workspace の Auth Key が付与する範囲に絞り込まれます。resource=https://api2.transloadit.com(末尾のスラッシュの有無は問いません)は、Vercel Connect⁠ の連携など、REST API を直接呼び出すアプリケーション用の api2 トークンを発行します。このトークンには、Auth Key のスコープに絞り込まれた要求済みスコープが含まれ、scope が省略された場合は、そのキーが付与するすべてのスコープが含まれます。ただし、グラントに Auth Key または Template 認証情報の管理権限(auth_keys:*、template_credentials:*、またはそれらを含意するグローバルな read/write)が含まれることはないため、長期的に使用できる認証情報を作成したり、開示したりすることはできません。それ以外の resource には、invalid_target が返されます。

クライアント登録、認可、失効における OAuth プロトコルエラーは、標準の error と error_description を含む本文を使用します。レート制限では RATE_LIMIT_REACHED が返されることがあります。

/token では、authorization_code と refresh_token に対する OAuth グラントエラーは、標準の error と error_description を含む本文を使用します。レート制限では RATE_LIMIT_REACHED(429)が返され、予期しない内部障害では SERVER_500(500)が返されます。グラントが識別される前に拒否された不正な形式のリクエストには、HTTP Basic チャレンジ(401)が返される場合があります。Basic 認証情報が指定されていた場合は、TOKEN_INVALID_REQUEST が返される場合があります。

Bearer トークン(クライアント認証情報)

Auth Key と Auth Secret を保持する CI ジョブ、サーバー、およびその他のヘッドレスクライアントは、Transloadit API が直接処理する OAuth 2.0 の client_credentials グラントを使用して、それらを短寿命の Bearer トークンと交換します。同意操作を行うブラウザーがない場合に使用してください。対話型 MCP クライアントは、前述のように URL で接続してください。エンドポイントの完全なリファレンスについては、/token API ドキュメントを参照してください。

トークンの使用

API リクエストで、トークンを Authorization: Bearer <access_token> として渡します。リクエストが有効な Bearer トークンで認証されると、API2 は Signature Authentication が満たされているとみなし、Signature の検証をスキップします。Signature Authentication が適用されるのは、キーとシークレットを使用するリクエストだけです。スコープとオーディエンスのチェックは引き続き適用されます。mcp オーディエンスは MCP サーバーで受け付けられ、MCP サーバーはサービス認証情報を使用して、それを API2 に中継します。通常の API2 エンドポイントに直接提示した場合は拒否されます。params 内の auth.key は省略できますが、params エンベロープを想定するエンドポイントでは、引き続きそのエンベロープが必要です。

curl --fail-with-body -sS --request POST \
  --url 'https://api2.transloadit.com/assemblies' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'params={"template_id":"YOUR_TEMPLATE_ID"}'

/ai/chat の MCP 自動認証

/ai/chat の Steps が Transloadit でホストされている MCP サーバーを呼び出す場合、API2 は短寿命の Bearer トークンを自動的に発行して挿入できます(自動認証)。これは、MCP サーバーのエントリーごとに有効化するオプトイン方式です。

{
  "mcp_servers": [
    {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "auth": "transloadit"
    }
  ]
}

動作:

  • auth: "transloadit" が設定され、Authorization ヘッダーが存在しない場合、API2 はトークンを発行し、Authorization: Bearer <token> を挿入します。
  • mcp_servers[].headers に Authorization がすでに指定されている場合は、そのまま変更されません。
  • 自動認証は、Transloadit が管理する次のエイペックスホストとサブドメインに対し、HTTPS 経由でのみ機能します。transloadit.com、*.transloadit.com、transloadit.dev、*.transloadit.dev、transloadit.website、*.transloadit.website、transloadit.work、*.transloadit.work。
  • URL はポート 443 を使用し、パスは正確に /mcp、または /mcp/ 配下のサブパスである必要があります。
  • URL に認証情報、クエリ文字列、またはフラグメントを含めてはいけません。
  • Auth Key は、安全な MCP スコープである assemblies:write、assemblies:read、templates:read のうち、少なくとも 1 つを付与している必要があります。
  • 発行されるトークンは、これらの安全な MCP スコープと Auth Key のスコープの共通部分に絞り込まれます。Auth Key が付与していないスコープを取得することはありません。

よくある質問

Transloadit は送信するリクエストに Signatures を含めますか?

Transloadit は、サーバーが真正性を検証できるように、Webhook リクエストに署名します。Webhook の署名は、Transloadit に送信される API リクエストを認証する HMAC とは別のものです。

Auth Secret を Bearer トークンとして使用できないのはなぜですか?

前述のサーバー間のトークン交換を除き、Auth Secret をクライアントに送信したり、API リクエストのパラメーターに含めたりしてはいけません。POST /token は、HTTPS 経由で Auth Secret を HTTP Basic のパスワードとして送信するため、バックエンドからのみ呼び出す必要があります。署名付きリクエストでは、シークレットはバックエンドに保持され、HMAC のキーとして使用されます。これにより、悪意のある第三者が署名付きリクエストを傍受し、アカウントへのリクエストを偽装することを防ぎます。好みのシークレット管理システムを使用して、Auth Secret を安全に保管してください。たとえば、Vault⁠、AWS Secrets Manager⁠、GCP Secret Manager⁠、Kubernetes Secrets⁠ などがありますが、選択したバックエンドプラットフォームに応じて適したものは、ほかにも多数あります。

補足

Auth Secrets が、アプリケーションのフロントエンドの一部に含まれたり、ユーザーに公開されたりすることが_決してない_ようにしてください。

本文内のキーはどの順序にする必要がありますか?

本文内のキーの順序は任意ですが、どの順序を選択する場合でも、Signature の生成時と一貫させる必要がある点が重要です。生成されるハッシュは JSON の内容に依存し、順序が異なると別のハッシュが生成されるため、リクエストが拒否されます。

前のページ ← レスポンスコード次のページ ウェブフック →
サポートに問い合わせる
Transloadit稼働状況を確認中…

製品

  • サービス
  • 料金
  • デモ EN (English)
  • ツール
  • セキュリティ
  • サポート

会社

  • 会社概要/プレス
  • ブログ/採用情報 EN (English)
  • 比較/コンプライアンス対応表
  • 研究 EN (English)
  • オープンソース
  • ソリューション
  • ウェブの先駆者たち

ドキュメント

  • はじめに
  • トランスコーディング
  • よくある質問
  • API
  • ガイド EN (English)/開発のヒント
  • 対応フォーマット

その他

  • プラットフォームの稼働状況⁠
  • コミュニティフォーラム⁠
  • Uppy
  • tus⁠

© 2009–2026 Transloadit-II GmbH

Transloadit®、tus®、Uppy® は、米国における Transloadit-II GmbH の登録商標です。

プライバシー EN (English)利用規約 EN (English)運営者情報 EN (English)商標 EN (English)DMCA ポリシー EN (English)
EnglishDeutschEspañolFrançaisPortuguês (Brasil)日本語