認証
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 を必須にするには、次の操作を行います。
- アカウントの Workspace 設定に移動します。
- API 設定セクションで、正しい Signature を必須にするオプションを有効にします。
- 自動保存が完了するまで待ちます。
有効な Bearer トークンは、Workspace と Template の設定を含め、Signature の要件をバイパスします。トークンのスコープとオーディエンスの制限は引き続き適用されます。これらの設定は、Assembly のステータス、キャンセル、再開可能なアップロードの URL など、ケイパビリティに基づくアクセスに認証を追加するものではありません。Assembly IDs とケイパビリティ URL は非公開にし、各エンドポイントの認証ガイダンスに従ってください。
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 を計算するには、次の手順を実行します。
- フロントエンドで、上記の JavaScript オブジェクトを JSON 文字列に変換し、バックエンドに送信します。
- バックエンドで、Auth Secret をキーとし、Auth Key の
signature_algoに設定されたアルゴリズムを使用して、この文字列に対する RFC 6234 準拠の HMAC の 16 進数表現の Signature を計算します。新しい Auth Keys のデフォルトはsha384です。アルゴリズムが設定されていない従来の Auth Keys は、sha384、sha256、またはsha1を受け付けます。signature文字列の先頭に、小文字のアルゴリズム名を付けます。たとえば、デフォルトのアルゴリズムではsha384:<HMAC-signature>を使用します。この文字列をフロントエンドに送信できます(ただし、フロントエンドからの正当なリクエストであることを保証するための適切なチェックを行っていることが前提です)。 - フロントエンドで、この値を含む
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 を返します。
手順をまとめると、次のようになります。
paramsフィールドとして Transloadit に送信する JSON ペイロードを生成します。- Auth Secret をキーとして使用し、ペイロードの内容に基づいて Signature を計算します。
signatureフィールドに Signature を渡して、Transloadit にリクエストを送信します。- Transloadit は、アカウントの Auth Secret とペイロードの内容を使用して、同じ Signature を計算します。
- 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 の具体的な実装の詳細を確認したい場合(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 は、次の手順で生成します。
expクエリパラメーターを追加し、それ以降は Smart CDN が Signature を受け付けなくなる将来の時刻を定義します。これは、ファイルへのアクセスを時間的に制限するのに役立ちます。有効期限は、UNIX エポック(UTC の 1970 年 1 月 1 日の開始時点の午前 0 時)からのミリ秒数で表します。このパラメーターは任意ですが、常に有効期限を設定することを強くお勧めします。たとえば、exp=1722517200000を使用する Signature は、2024 年 8 月 01 日(木)13:00:00 GMT まで有効です。auth_keyクエリパラメーターを追加し、Signature の作成に使用する Auth Secret に対応する Auth Key を定義します。このパラメーターが設定されていない場合、Transloadit の API は、Smart CDN が有効になっている最も古い Auth Key のペアが Signature に使用されたとみなします。auth_keyパラメーターを設定すると、ユーザーの利用を中断することなく Auth Key をローテーションできるため、設定することを強くお勧めします。例:auth_key=23c96d084c744219a2ce156772ec3211URLSearchParams.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に並べ替えられます。- 次の値を連結して、署名対象の文字列を構築します。
[your-workspace]/[template-name]/[file-path]?[sorted-parameters][your-workspace]、[template-name]、[file-path]の値は、URL で安全に使用できる文字だけが含まれるよう、URL エンコードする必要があります。この文字列の先頭にはスラッシュを付けない点に注意してください。[sorted-parameters]が空の場合、?文字は省略する必要があります。 - Auth Secret をキーとし、SHA256 をハッシュアルゴリズムとして、署名対象の文字列に対する RFC 6234 準拠の HMAC の 16 進数表現の Signature を計算します。16 進数表現の Signature の先頭に、小文字のアルゴリズム名とコロン、つまり
sha256:を付けます。たとえば、SHA256 の場合はsha256:[hmac-signature]を使用します。 - プレフィックス付きの 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 がアカウントの外に出ることはありません。
- 検出。 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 メタデータには、以下のエンドポイントが記載されています。 - クライアントの識別。 次のいずれかを行います。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.1URL である必要があります。シークレットを使用して登録されたクライアントは、すべてのトークンリクエストと失効リクエストで、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を使用してください。 - 同意。 クライアントは、
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 秒後に失効します。 - トークン。 クライアントは、
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 日間有効になります。 - 失効。 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 の内容に依存し、順序が異なると別のハッシュが生成されるため、リクエストが拒否されます。