認証コードの無効化¶
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 を保持して管理者に連絡し、結果を確認してください。自動的な再認可や、エラーに基づいて無効化が完了したと判断することを避けてください。 |