新しい Auth Key を作成する
認証済みの Workspace 用に、スコープを限定した Auth Key を作成します。
https://api2.transloadit.com/ auth_keys作成時のレスポンスには、新しい Auth Secret が含まれます。受け取ったら安全に保管してください。後からの取得はデフォルトで無効になっています。Auth Key のシークレットを取得を通じて後から 1 回表示する必要がある場合にのみ、作成時に can_show_auth_secret を true に設定してください。
Smart CDN を有効にしたキーは、通常の API リクエストの認証や Bearer トークンの発行にも使用できます。Smart CDN を有効にしても、追加のスコープは付与されません。連携に必要な権限だけを付与してください。Auth Secret はサーバー上で保管してください。連携ごとに独立した権限や失効の管理が必要な場合は、別々のキーを使用できます。
追加の、より強力な Webhook Signature を有効にするには、notification_signature_algo を設定してください。これは API リクエストの署名とは独立しており、従来の SHA-1 フォーム Signature は変更されません。
リクエストの例
適切な Bearer トークンを TRANSLOADIT_TOKEN に設定し、curl を使用してサーバー側のシェルでこのリクエストを実行してください。トークンが必要な場合は、以下のセットアップ手順を展開してください。
Bearer トークンが必要ですか?
curl と jq が利用できる信頼されたサーバー側のシェルで、TRANSLOADIT_KEY と TRANSLOADIT_SECRET に、それぞれ Auth Key と Auth Secret を設定してください。両方の認証情報と生成されたトークンは秘密に保ってください。このセットアップをブラウザーのコードで実行しないでください。
まず、このエンドポイントに必要なスコープを持つトークンを作成します。Auth Key には、それらのスコープがすでに付与されている必要があります。
if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
--request POST \
--url 'https://api2.transloadit.com/token' \
--user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'aud=api2' \
--data-urlencode 'scope=auth_keys:write')"; then
printf '%s\n' "$TOKEN_RESPONSE" >&2
exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
jq -er '.access_token | strings | select(length > 0)')" || exit 1
このシェルを開いたまま、以下のリクエストを実行してください。トークンが有効な間は再利用してください。
curl --fail-with-body -sS --request POST \
--url "https://api2.transloadit.com/auth_keys" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"scope":"assemblies:read,assemblies:write","description":"Backend Assembly integration"}'
認証
このエンドポイントは、署名付きの params または Bearer トークンを受け付けます。設定手順については、認証を参照してください。
Auth Key または Bearer トークンに必要なスコープ: auth_keys:write。
Signature 付きリクエストには、signature と、将来の時刻を示す params.auth.expires タイムスタンプの両方が必要です。Bearer トークンには、どちらも必要ありません。
フォームフィールド
コンテンツタイプ: application/x-www-form-urlencoded
params(JSON 文字列)、必須。JSON エンコードされたオブジェクトで、サポートされるキーは以下のとおりです。signature(文字列)。署名付きリクエストでは必須です。Bearer トークンを使用する場合は、このフィールドを省略してください。
params フィールド内でサポートされるキー
この一覧の認証フィールドは、署名付きリクエストに適用されます。Bearer トークンを使用する場合は、params.auth と、それとは別の signature フィールドを省略できます。以下の認証方式ごとのリクエストパラメーターを比較してください。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
| フィールド | 型と説明 |
|---|---|
params.署名付きリクエストでは必須。Bearer トークンを使用する場合は任意 | Auth Keys リクエスト用の Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params.必須 | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params.必須 | stringリクエストの認証に使用する Transloadit API キー |
params. | string (最小長: 32, 最大長: 64)ASCII の英字、数字、ハイフン、アンダースコアからなる 32–64 文字のカスタム Auth Key 値。省略すると API2 がランダムな値を生成します。予測可能な値を選ぶよりも、この方法を優先してください。既存の Auth Key 値は引き続き有効であり、既存のキーのまま値を変更することはできません。 検証パターン(正規表現)^[A-Za-z0-9_-]+$ |
params. | boolean | 0 | 1生成されたシークレットを、作成後に一度だけ表示できるかどうか。デフォルトは false です。作成時のレスポンス自体には、この設定にかかわらずシークレットが含まれます。安全に保管してください。 |
params. | string (最大長: 255)人が読んで理解できる Auth Key の説明です。ほとんどの絵文字を含め、Unicode の基本多言語面外の文字はサポートされていません。 検証パターン(正規表現)^[\u0000-\ud7ff\ue000-\uffff]*$ |
params. | boolean | 0 | 1この Auth Key を、通常の API リクエストや Bearer トークンの発行に加えて、Smart CDN の URL の認証にも使用できるかどうか。各操作には、それぞれに対応するスコープが引き続き必要です。作成時に省略した場合のデフォルトは false です。更新時に省略した場合は現在の値が維持されます。Smart CDN の使用を無効にするには、false を明示的に送信してください。 |
params. | string | integer各 Signature を一意にし、Signature の意図しない再利用を防ぐために、署名付きリクエストのパラメーターに含める一意のランダムな値。 |
params. | "sha256" | "sha384" | null追加の Transloadit-Signature Webhook ヘッダーに使用するアルゴリズムです。従来の SHA-1 の signature フォームフィールドに変更はありません。デフォルトは null(追加ヘッダーなし)です。更新時に省略すると現在の値が保持され、null を指定すると追加ヘッダーが無効になります。API リクエストの署名とは独立しています。 |
params.必須 | stringカンマ区切りの Auth Key スコープ。重複するスコープは API2 によって正規化されます。 検証パターン(正規表現)^(?:[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*,)*[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:read|write|auth_keys:write|auth_keys:read|assemblies:write|assemblies:read|assembly_notifications:write|dam:read|dam:write|template_credentials:read|template_credentials:write|billing:read|queues:read|smart_cdn:sign|templates:read|templates:write|storage_grants:write)[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:,[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:(?:read|write|auth_keys:write|auth_keys:read|assemblies:write|assemblies:read|assembly_notifications:write|dam:read|dam:write|template_credentials:read|template_credentials:write|billing:read|queues:read|smart_cdn:sign|templates:read|templates:write|storage_grants:write)[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*)?)*$ |
params. | "sha1" | "sha256" | "sha384" | nullこの Auth Key でリクエストに署名するために使用する HMAC アルゴリズムです。作成時、通常の API キーのデフォルトは |
認証方式別のリクエストパラメーター
署名付き params
Auth Key を params.auth.key として含めてください。リクエストに署名する場合は、将来の時刻を示す params.auth.expires タイムスタンプを含め、Signature を別の signature フィールドで送信してください。以下のフィールド定義では、params 内のパスを使用しています。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.auth, params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.notification_signature_algo, params.scope, params.signature_algo
Bearer トークンを使用する場合
Bearer トークンを Authorization ヘッダーで送信してください。params.auth と、それとは別の signature フィールドは省略できます。他の必須パラメーターの要件は引き続き適用されます。以下のフィールド定義では、params 内のパスを使用します。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.notification_signature_algo, params.scope, params.signature_algo
| フィールド | 型と説明 |
|---|---|
params. | Auth Keys リクエスト用の Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params. | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params. | stringリクエストの認証に使用する Transloadit API キー |
レスポンス
レスポンスボディの例を以下に示します:
{
"auth_key": {
"auth_key": "example_auth_key",
"auth_secret": "example_secret_store_securely",
"can_show_auth_secret": false,
"created": "2026-09-12T10:00:00.000Z",
"description": "Backend Assembly integration",
"id": "ca7644b763c848e6af4f4ccf3eaea622",
"is_active": true,
"is_allowed_for_smartcdn": false,
"last_used": null,
"modified": "2026-09-12T10:00:00.000Z",
"notification_signature_algo": null,
"scope": "assemblies:read,assemblies:write",
"signature_algo": "sha384"
},
"message": "Your auth key was successfully created.",
"ok": "AUTH_KEY_CREATED"
}2xx 成功
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
auth_key必須 |
|
auth_key.必須 | string (最大長: 64)検証パターン(正規表現)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.必須 | string |
auth_key.必須 | boolean |
auth_key.必須 | string | nullAuth Key が作成された時刻を表す ISO 8601 形式のタイムスタンプ。作成タイムスタンプが記録されていない場合は null。 検証パターン(正規表現)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.必須 | string (最大長: 255)検証パターン(正規表現)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.必須 | string |
auth_key.必須 | boolean |
auth_key.必須 | boolean |
auth_key.必須 | string | nullおおよその最終使用時刻を示す ISO 8601 タイムスタンプです。タイムスタンプが記録されていない場合は null です。使用状況は非同期に追跡され、バッチ単位で永続化されるため、この値への反映はリクエストより遅れることがあります。正確な監査用タイムスタンプではなく、null であっても、そのキーが一度も使用されていないことの証明にはなりません。 検証パターン(正規表現)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.必須 | string | nullAuth Key の設定が最後に更新された日時を表す ISO 8601 形式のタイムスタンプです。変更タイムスタンプが記録されていない場合は null です。使用状況の追跡情報は 検証パターン(正規表現)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key. | "sha256" | "sha384" | null追加の Transloadit-Signature Webhook ヘッダーに使用するアルゴリズムです。従来の SHA-1 の signature フォームフィールドに変更はありません。デフォルトは null(追加ヘッダーなし)です。更新時に省略すると現在の値が保持され、null を指定すると追加ヘッダーが無効になります。API リクエストの署名とは独立しています。 |
auth_key.必須 | string | null (最大長: 512)検証パターン(正規表現)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.必須 | null | string |
message必須 | string (最小長: 1) |
ok必須 | string (常に: "AUTH_KEY_CREATED") |
エラーレスポンス
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
assembly_id | string |
error | string (最小長: 1) |
http_code | number | string
|
message | string人が読んで理解できる形式のエラー説明です。文言は変わる場合があるため、特定の失敗を処理する際は |
reason | null | string | number | boolean | Array<任意の値> | object次のいずれかのスキーマが適用される場合があります: nullstringnumberbooleanArray<任意の値>Array<任意の値>配列要素のスキーマ任意の値objectobject追加プロパティのスキーマ任意の値 |
HTTP 400
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "AUTH_KEY_NOT_CREATED"
Auth Key を作成できませんでした。
レスポンスには追加のフィールドが含まれる場合があります。