認証コードを生成¶
POST /api/v1/offline_token/temporary_auth_code/create
概要¶
現在のワークスペースに対して、フロントエンドが一時的なオフラインアクセス Token を引き換えるための、短時間有効なワンタイム認証コードを作成します。
呼び出し前の準備と使用手順¶
expires と任意の roles を送信します。API は authCode を返し、Token を直接返しません。code はそのまま同一サイトのフロントエンド認証エントリポイントへ渡し、フロントエンドサービスが GET /api/v1/auth-token/get?authCode=... で引き換えます。また、コンソールの既存の接続規約に従って /redirect_auth/{authCode}?overwrite=true&to=xxx を開くこともできます。中間ページが code を消費し、overwrite=true は現在のログイン状態を上書きし、省略した場合は一時的な使用となります。to は URL エンコードされたサイト内の相対アドレスです。コンソールドメインとフロントエンド API ドメインは、同一サイトの接続アドレスに従って選択してください。引き換えに成功すると code は直ちに削除され、再利用できません。同時実行される引き換えと失効のうち、1 つのフローのみが消費できます。authCode を DF-API-KEY、X-FT-Auth-Token、またはオフライン Token として業務 API を直接呼び出さないでください。expires はアクセス Token の申請有効期間で、単位は秒です。期限は code の作成時点から計算され、引き換えによって再計時されません。実際の値は、リクエスト値とサイトの Token 上限のうち小さい方になります。code 自体の expiresIn はデフォルト 600 秒で、サイト設定によって決まり、expires とは異なります。Token の申請有効期間が先に切れた場合、code のキャッシュが残っていても引き換えることはできません。ロールリストは、まず現在のワークスペースのロールと 1 項目ずつ照合して確認してください。code の作成時に各ロールが完全に検証されることはなく、対象へのアクセス権限を保有していることも証明されません。ロール権限は引き換えて Token を生成する際に計算されキャッシュされます。その後の権限変更が発行済み Token に自動反映されることは保証されません。未使用の code はワンタイム認証コードを失効で失効できます。引き換え後の Token の有効期間と失効の範囲については後述します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| expires | integer | Y | 必須。アクセス Token の申請有効期間で、1〜604800 秒です。実際にはサイトの上限にも制約されます。code の作成時点から計時し、code 自体の TTL は制御しません。 null 許可: False $maxValue: 604800 $minValue: 1 例: 3600取得または入力方法: 実際のアクセス作業に応じて秒数を選択します。例えば 3600 は 1 時間です。短い作業では短めの有効期間を設定することを推奨します。 |
| roles | array | 任意。ロール UUID の配列です。省略または [] の場合はデフォルトで shared 共有アクセス ID となり、デフォルトの readOnly ではありません。現在、ロールごとの有効性の厳密な検証は行われないため、クライアント側で事前に確認する必要があります。null 許可: False 例: ["readOnly"]取得または入力方法: ロール一覧 の content.data[].uuid から同一ワークスペースの対象ロール(wsAdmin/general/readOnly、または role_ カスタムロールなど)を取得し、最小限のアクセス要件に応じて選択します。 |
|
| roles[*] | string | 条件付き必須 | 単一の非 null ロール識別子文字列。 null 許可: False 例: readOnly取得または入力方法: ロール一覧 から単一のロール UUID をコピーします。表示名は入力しないでください。 |
パラメータの補足説明¶
その後の引き換えはフロントエンドサービスが処理します: GET <FrontEndpoint>/api/v1/auth-token/get?authCode=<创建返回的authCode>。成功時の content には token、tokenType=custom、workspaceUUID、expiresAt(Unix 秒)が含まれ、expiresAt は最終的なアクセス期限です。この引き換えレスポンスは本作成 API のものではありません。引き換えの失敗は 400 ft.NotFoundAuthCode、401 ft.OfflineTokenExpired、またはワークスペースエラーとなる場合があります。code の期限切れまたは失効は、まだ引き換えていない code にのみ影響し、以前に引き換え済みの Token は失効しません。現在、旧来の Token 失効 API には新しいバージョンの Token に対する互換性の制限があるため、後続ページの説明に従って確認してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/offline_token/temporary_auth_code/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"roles":["readOnly"],"expires":3600}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.authCode | string | ワンタイム認証コード。同一サイトのフロントエンド認証引き換えエントリポイントへそのまま渡す必要があり、分解したり独自に結合したりしないでください。 |
| content.action | string | 固定値 offline_custom_token で、custom オフライン Token に引き換え可能なワンタイム code であることを示します。 |
| content.workspaceUUID | string | API Key が属するワークスペース UUID で、以降のアクセス範囲でもあります。 |
| content.expiresIn | integer | code 自体の有効期間(秒)。デフォルトは 600 で、最終的な Token のアクセス有効期間ではありません。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"authCode": "AUTH-CODE-EXAMPLE.1785430800",
"action": "offline_custom_token",
"workspaceUUID": "wksp_example",
"expiresIn": 600,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
ロールが無効であっても、作成時にロールが存在しないというエラーが返されることは保証されません。作成に成功した後も、引き換え結果と対象画面の権限チェックによって実際のアクセスを検証する必要があります。現在の API Key のワークスペースのみが対象で、単一リソースのホワイトリストパラメータは提供されていません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではない | 一部の json ファイルの形式エラー | 単一の JSON オブジェクトを送信してください。 |
| 401 | ft.WKSPNotExistOrReleased | 作成時のリアルタイムチェックでワークスペースが削除または解放済みであることが判明 | ワークスペースが存在しない/または解放済み | API Key が属するワークスペースが有効か確認してください。 |
| 500 | ft.InternalServerError | キャッシュまたはその他の内部処理の失敗 | 内部エラー | traceId を保持したうえで管理者に連絡して結果を確認してください。自動で再認証を繰り返したり、エラーに基づいて失効が完了したと判断したりしないでください。 |