クイックOIDCpowered byCygiene（スカイゲートテクノロジズ）

パブリック API 仕様

テナントのリソース（利用ユーザ・OIDC アプリ・テナント設定）をプログラムから操作する REST API です。外部システム連携や自動化にご利用ください。

概要

管理コンソールのオリジン配下 /api/v1 で提供する JSON over HTTPS の REST API です。エンドポイントはパスバージョニング（/api/v1/...）を用います。

ベース URL
https://（管理コンソールのオリジン）/api/v1
形式
リクエスト・レスポンスとも JSON（UTF-8）。
認証
API キー（Bearer）。
レート制限
現時点では設けていません（将来拡張）。

事前準備

利用開始には、管理コンソールで次の 2 つが必要です（テナント設定 > 「API キー」タブ）。

  1. REST API 経路を有効化する（既定は無効。 無効の間は有効なキーでもアクセスできません）。
  2. API キーを発行し、必要なスコープと 有効期限を設定する。平文は発行時に一度だけ表示されます（以降は再表示できません）。

認証

すべてのリクエストに Authorization: Bearer <API キー> ヘッダを付与します。 キーは単一テナントに紐づき、操作は発行元テナントの範囲に限定されます（テナント間のデータは 分離されます）。

curl https://（管理コンソールのオリジン）/api/v1/users \
  -H "Authorization: Bearer wfk_xxxxxxxx..."

スコープ（権限）

API キーには、リソースごとに権限レベルを付与します。付与されていないリソース・不足レベルの 操作は拒否されます（最小権限）。レベルは read ⊂ write ⊂ full の階層で、上位は 下位を内包します。

users
利用ユーザ。read / write / full。
oidc-apps
OIDC アプリ。read / write / full（full はクライアントシークレット再発行を含む）。
tenant-settings
テナント設定。read / write のみ（作成・削除が無いため full はありません）。
read
参照（一覧・取得）。
write
read に加え、作成・更新（利用ユーザの状態切替を含む。削除は不可）。
full
write に加え、削除。OIDC アプリではクライアントシークレット再発行を含む。

ページング・フィルタ

一覧はカーソルページングに対応します。?limit=（1〜100・既定 50）と?cursor= を指定し、応答の nextCursor（最終ページではnull）を次リクエストの cursor に渡します。利用ユーザ一覧は?status=active|disabled と ?q=（表示名・メールの部分一致）で 絞り込めます。

{
  "items": [ /* ... */ ],
  "nextCursor": "eyJ0..."   // 最終ページでは null
}

エンドポイント

利用ユーザ

メソッドパス必要スコープ説明
GET/api/v1/usersusers:read一覧（フィルタ・ページング対応）
POST/api/v1/usersusers:write作成
GET/api/v1/users/{id}users:read取得
PATCH/api/v1/users/{id}users:write更新（部分更新・状態切替）
DELETE/api/v1/users/{id}users:full削除

OIDC アプリ

メソッドパス必要スコープ説明
GET/api/v1/oidc-appsoidc-apps:read一覧
POST/api/v1/oidc-appsoidc-apps:write作成（応答に clientSecret を一度だけ含む）
GET/api/v1/oidc-apps/{id}oidc-apps:read取得
PATCH/api/v1/oidc-apps/{id}oidc-apps:write更新（部分更新）
DELETE/api/v1/oidc-apps/{id}oidc-apps:full削除
POST/api/v1/oidc-apps/{id}/secretoidc-apps:fullクライアントシークレット再発行（二段階確認）

テナント設定

メソッドパス必要スコープ説明
GET/api/v1/tenant-settingstenant-settings:read自テナント設定の取得
PATCH/api/v1/tenant-settingstenant-settings:write自テナント設定の更新

二段階確認（クライアントシークレット再発行）

不可逆な操作であるクライアントシークレット再発行のみ、二段階確認が必要です（oidc-apps:full）。削除などその他の操作に二段階確認はありません。

  1. POST /api/v1/oidc-apps/{id}/secret を本文なしで呼ぶと、影響の プレビューと confirmationToken が返ります（202）。
  2. 同じトークンを本文に添えて再度呼ぶと、確定・実行され新しい clientSecret が 返ります（200）。トークンは短時間のみ有効です。
# 1) プレビュー + 確認トークン
POST /api/v1/oidc-apps/{id}/secret
→ 202 { "preview": { ... }, "confirmationToken": "..." }

# 2) 確定
POST /api/v1/oidc-apps/{id}/secret
{ "confirmationToken": "..." }
→ 200 { "clientSecret": "secret_..." }

エラーとステータスコード

エラー応答は統一形式です。details は省略される場合があります。

{
  "error": {
    "code": "FORBIDDEN",
    "message": "権限が不足しています"
  }
}
200 / 201 / 204
成功（取得・更新 / 作成 / 削除）。
202
シークレット再発行の第1段階。プレビューと確認トークンを返す。
400
入力不正（INVALID_INPUT）／確認トークン無効・期限切れ（INVALID_CONFIRMATION）。
401
認証失敗（UNAUTHENTICATED）。キー無し・不正・失効・期限切れ。
403
スコープ不足（FORBIDDEN）／REST 経路が無効（ROUTE_DISABLED）。
404
対象が存在しない、または他テナントのリソース（NOT_FOUND）。
パブリック API 仕様 | ヘルプ