Bearer トークンを作成する
Auth Key の認証情報を、スコープを限定した Bearer トークンと交換します。
https://api2.transloadit.com/ tokenこれは OAuth 2.0 のトークンエンドポイントです。ヘッドレスクライアントは、client_credentials グラントを使用して Auth Key と Auth Secret を短寿命の Bearer トークンと交換します。この処理は Transloadit API が直接行います。URL で接続した MCP クライアントは、authorization_code グラントを使用してコンソールの同意画面から取得した認可コードを引き換えます(PKCE S256、HTTP Basic 認証情報なし)。また、refresh_token グラントを使用して、得られたリフレッシュトークンをローテーションします。
/token では、authorization_code と refresh_token の OAuth グラントエラーに、標準の error と error_description を含むレスポンスボディを使用します。レート制限では RATE_LIMIT_REACHED (429) が返され、予期しない内部障害では SERVER_500 (500) が返されます。グラントが特定される前に拒否された不正な形式のリクエストには、HTTP Basic チャレンジ (401)、または Basic 認証情報が指定されていた場合は TOKEN_INVALID_REQUEST が返されることがあります。
クライアント認証情報によるトークンは、Auth Key/Secret を使用してサーバー側で発行されます。UI からトークンを作成できるようにする場合は、バックエンドから /token を呼び出してください(ブラウザーから直接呼び出すことは決してしないでください)。
キャンセル済みの Workspaces では、新しい Bearer トークンを作成できません。キャンセル後の読み取りがドキュメントで明示的に許可されているエンドポイントでは、代わりに既存の有効な Auth Key を使用して、署名付き読み取りの手順に従ってください。請求については、専用の署名付きアクセスの手順があります。
リクエストには application/x-www-form-urlencoded を使用する必要があります。client_credentials グラントには HTTP Basic 認証も必要です。
curl と jq が利用できる信頼できるサーバー側のシェルで、TRANSLOADIT_KEY と TRANSLOADIT_SECRET に、それぞれ Auth Key と Auth Secret を設定してください。両方の認証情報と生成されたトークンは秘密にしてください。この設定をブラウザーのコードで実行することは決してしないでください。
この例では、Assembly の読み取りと書き込みのアクセス権を要求し、同じシェルでの後続のリクエストに使用するため、返された access_token を TRANSLOADIT_TOKEN として保存します。別のエンドポイントを使用する場合は、代わりにそのエンドポイントに記載されているスコープを使用してください。その Auth Key で、それらのスコープがすでに許可されている必要があります。Auth Key または Bearer トークンで認証するエンドポイントでは、リクエスト例に適切なトークン設定が含まれています。
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=assemblies:read assemblies: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
認証
次の grant_type の値には、Auth Key とシークレットを使用した HTTP Basic 認証が必要です: client_credentials。サポートされているその他の値には、アカウントの認証情報は必要ありません。それらのリクエストでは Authorization ヘッダーを送信しないでください。ただし、グラント固有の証明は引き続き必要です。
フォームフィールド
コンテンツタイプ: application/x-www-form-urlencoded
次のフィールドは、それぞれ最大 1 回送信できます: aud, client_assertion, client_assertion_type, client_id, client_secret, code, code_verifier, grant_type, redirect_uri, refresh_token, resource, scope。
完全な JSON スキーマ
クライアント認証情報、認可コード、リフレッシュトークンの各グラント用の OAuth 2.0 トークンリクエストフォーム。
このオブジェクトについて列挙されているフィールド以外のフィールドも受け付けます。
| フィールド | 型と説明 |
|---|---|
aud | string
|
client_assertion | stringクライアントの公開済みの鍵のいずれかで署名された JWT(RFC 7523)で、メタデータで |
client_assertion_type | string
|
client_id | string動的登録によるクライアント識別子、またはクライアントのメタデータドキュメントの HTTPS URL。 |
client_secret | string
|
code | string同意後にクライアントのリダイレクト URI に送信される、一度限りの認可コード。 |
code_verifier | string認可開始時に SHA-256 ダイジェストが |
grant_type必須 | "authorization_code" | "client_credentials" | "refresh_token"実行する OAuth 2.0 のグラント。 |
redirect_uri | string認可リクエストで使用するリダイレクト URI。 |
refresh_token | string認可グラントのリフレッシュトークン。 |
resource | stringトークンの対象となる保護リソースで、ホストされた MCP エンドポイント( |
scope | string
|
トークンの使用
API リクエストでは、トークンを Authorization: Bearer <access_token> として渡してください。有効な Bearer トークンでリクエストが認証されると、API2 は
Signature Authentication が満たされているとみなし、Signature の検証をスキップします。Signature Authentication が必須となるのは、キー/シークレットを使用するリクエストのみです。スコープのチェックは引き続き適用されます。デフォルトの api2 オーディエンスは通常の API2 エンドポイントで受け入れられ、デフォルトで 21,600 秒間有効です。mcp オーディエンスは MCP サーバーで受け入れられ、MCP サーバーはサービス認証情報を使用してこれを API2 に中継します。通常の API2 エンドポイントに直接提示された場合は拒否され、デフォルトで 604,800 秒間有効です。レスポンスの expires_in の値を正としてください。
レスポンス
レスポンスボディの例を以下に示します:
{
"access_token": "opaque-token",
"expires_in": 21600,
"scope": "assemblies:read assemblies:write",
"token_type": "Bearer"
}2xx 成功
JSON レスポンスの本文。 application/json
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには、このオブジェクトについて記載されているフィールドのみが含まれます。
| フィールド | 型と説明 |
|---|---|
access_token必須 | string (最小長: 1)後続の API リクエストの Authorization ヘッダーで送信するトークンです。秘密にしてください。 |
expires_in必須 | integer (最小値(境界値を含まない): 0)発行時点からのトークンの有効期間(秒単位)。有効期限が切れたら、新しいトークンをリクエストしてください。 |
refresh_token | string (最小長: 1)
|
scope必須 | string (最小長: 1, 最大長: 512)このトークンに付与されたスコープ(スペース区切り)。 検証パターン(正規表現)^(?: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)(?: (?: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))*$ |
token_type必須 | string (常に: "Bearer") |
HTTP 400
JSON レスポンスの本文。 application/json
レスポンスボディのスキーマ
完全な JSON スキーマ
次のいずれかのスキーマが適用される場合があります:
error: "GET_ACCOUNT_UNKNOWN_AUTH_KEY"
Workspace を取得できませんでした。これは不明な Auth Key です。
レスポンスには追加のフィールドが含まれる場合があります。
error: "TOKEN_INVALID_GRANT_TYPE"
グラントタイプが無効です。
レスポンスには追加のフィールドが含まれる場合があります。
error: "TOKEN_INVALID_REQUEST"
トークンリクエストが無効です。
レスポンスには追加のフィールドが含まれる場合があります。
必須プロパティ: error
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
error必須 | stringRFC 6749、7591、または 8707 のエラーコード( 検証パターン(正規表現)^(?:access_denied|invalid_client|invalid_client_metadata|invalid_grant|invalid_redirect_uri|invalid_request|invalid_scope|invalid_target|server_error|unauthorized_client|unsupported_grant_type)$ |
error_description | string人が読んで理解できる説明で、アカウントを名指しすることはありません。 |
HTTP 401
JSON レスポンスの本文。 application/json
レスポンスボディのスキーマ
完全な JSON スキーマ
次のいずれかのスキーマが適用される場合があります:
error: "SERVER_401"
認可が必要です。
レスポンスには追加のフィールドが含まれる場合があります。
error: "TOKEN_INVALID_CREDENTIALS"
クライアント認証情報が無効です。
レスポンスには追加のフィールドが含まれる場合があります。
必須プロパティ: error
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
error必須 | stringRFC 6749、7591、または 8707 のエラーコード( 検証パターン(正規表現)^(?:access_denied|invalid_client|invalid_client_metadata|invalid_grant|invalid_redirect_uri|invalid_request|invalid_scope|invalid_target|server_error|unauthorized_client|unsupported_grant_type)$ |
error_description | string人が読んで理解できる説明で、アカウントを名指しすることはありません。 |
HTTP 403
JSON レスポンスの本文。 application/json
レスポンスボディのスキーマ
完全な JSON スキーマ
次のいずれかのスキーマが適用される場合があります:
error: "TOKEN_INVALID_AUDIENCE"
オーディエンスが無効です。
レスポンスには追加のフィールドが含まれる場合があります。
HTTP 429
JSON レスポンスの本文。 application/json
レスポンスボディのスキーマ
完全な JSON スキーマ
リクエスト数の上限に達しました。
レスポンスには追加のフィールドが含まれる場合があります。
HTTP 500
JSON レスポンスの本文。 application/json
レスポンスボディのスキーマ
完全な JSON スキーマ
予期しないエラーが発生しました。
レスポンスには追加のフィールドが含まれる場合があります。