コンテンツにスキップ

認証コードの無効化



POST /api/v1/offline_token/temporary_auth_code/revoke

概要

現在のワークスペースでまだ交換されていないワンタイムのカスタム認証コードを無効化します。

呼び出し前の準備と使用手順

ワンタイム認証コードの作成の content.authCode から値をそのまま取得し、同じワークスペースで権限を持つ API Key を使用して送信します。無効化できるのは、この公開作成フローで生成された offline_custom_token コードのみです。その他の共有、スナップショット、または繰り返し交換可能な認証コードには使用できません。true が正常に返されると、まだ交換されていないコードは削除され、引き続き交換することはできません。コードと交換処理はロック内で直列に処理されます。交換が先に成功している場合、無効化はコードが存在しないことを返し、すでに生成された Token を遡って無効化することはありません。期限切れ、使用済み、または無効化済みのコードを再度無効化すると NotFoundAuthCode が返され、冪等な成功にはなりません。現時点では、同じ作成者 Key であることは検証されません。主な境界は同一ワークスペースおよびこのエンドポイントの権限です。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証資格情報。
例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
authCode string Y 必須のワンタイム認証コード。交換後の Token を送信したり、タイムサフィックスを独自に切り詰めたりしないでください。
null を許可: False
例: AUTH-CODE-EXAMPLE.1785430800
取得または入力方法: ワンタイム認証コードの作成が返す content.authCode を取得します。

パラメータ補足説明

コードを無効化しても、すでに交換済みの Token のアクセスを停止することはできません。交換リクエストがタイムアウトした場合は、まず連携側で Token を取得済みかどうかを確認してください。「無効化時にコードが見つからない」ことを、Token が無効になったと解釈しないでください。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/offline_token/temporary_auth_code/revoke' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"authCode":"AUTH-CODE-EXAMPLE.1785430800"}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。

フィールド 型 説明
content boolean 未交換のコードの削除に成功した場合は true です。
{
  "code": 200,
  "content": true,
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

認証、レート制限、および共通リクエストエラーの詳細は共通エラー定義を参照してください。

HTTP ステータス errorCode 発生条件 メッセージまたは応答の説明 対応方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメータの解析に失敗しました パラメータの位置、フィールド名、型、および値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効です リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正してください。
400 ft.JsonFormatError JSON のトップレベルがオブジェクトではありません JSON ファイルの形式の一部が誤っています 単一の JSON オブジェクトを送信してください。
400 ft.NotFoundAuthCode コードが存在しない、期限切れ、使用済み、このエンドポイントがサポートするカスタムのワンタイムコードではない、または並行処理でロックを取得できなかった 認証コードが見つかりません 作成応答の元の authCode を使用していることを確認してください。交換済みの場合は、再度交換することも、このコードで無効化することもできません。未完了の認可は業務の必要に応じて再作成してください。
403 ft.WorkspaceForbidden コードにキャッシュされたワークスペースが現在の API Key のワークスペースと異なる 現在のワークスペースへのアクセス権限がありません このコードを発行したワークスペースの Key を使用してください。ワークスペースを跨いで無効化しないでください。
500 ft.InternalServerError キャッシュまたはその他の内部処理に失敗しました 内部エラー traceId を保持して管理者に連絡し、結果を確認してください。自動的な再認可や、エラーに基づいて無効化が完了したと判断することを避けてください。

フィードバック

このページは役に立ちましたか?