Client Credentialsフロー

Client Credentialsフローは、サインインしたユーザーなしで組織の代理として動作するサーバー間統合に使用します。このガイドでは、OAuthアプリケーションの作成から最初のAPI呼び出しまでを説明します。

前提条件、ネットワークアクセス、セキュリティモデルをまだ確認していない場合は、先にセットアップガイドを読んでください。

実施する内容

OAuthアプリケーションを作成する — Prevu3Dにアプリを登録し、認証情報を取得する
サービスユーザーのアクセスを設定する — アプリに必要なデータへのアクセスを付与する
アクセストークンを取得する — 認証してAPIを使用するためのトークンを受け取る
API URLを見つける — 組織のベースURLを確認する（リージョンによって異なります）
最初の呼び出しを行う — 簡単なリクエストで接続をテストする

ステップ1：OAuthアプリケーションを作成する

Prevu3D Platformにログインします。
Settings → OAuthに移動します。
新しいアプリケーションを作成するにはクリックします。
OAuthフローとしてClient Credentialsを選択します。
アプリケーションに必要な権限を割り当てます（これによりレイヤー1：OAuthスコープが設定されます）。組織管理者が必要なスコープの決定を手伝ってくれます。
作成ボタンをクリックします。
Client IDとClient Secretをコピーして安全に保管します。すべてのAPIリクエストで必要になります。

ステップ2：サービスユーザーのアクセスを設定する

OAuthアプリケーションを作成すると、組織内に対応するサービスユーザーが自動的に作成されます。このサービスユーザーはAPIとのやり取り時にアプリケーションを表しますが、まだアクセス権はありません。

このステップでは、セキュリティモデルのレイヤー2と3をカバーします。サービスユーザーが表示できるノード（コンテンツアクセス）と、それらに対して実行できる操作（ロール/権限アクセス）です。

Settings → Usersに移動します。
サービスユーザーを見つけ、編集ボタンをクリックします（作成したOAuthアプリケーションと同様の名前のはずです）。
ユースケースに必要なノード（組織、ディビジョン、サイトなど）へのコンテンツアクセスをサービスユーザーに付与します。
サービスユーザーが必要な操作（読み取り、編集、管理など）を実行できるよう、それらのノードに適切なロール/権限を割り当てます。
変更を確認します。

ステップ3：アクセストークンを取得する

APIを呼び出すには、まずアクセストークンが必要です。Client IDとClient Secretを使用して、トークンエンドポイントにリクエストを送信します。

エンドポイント： POST https://cloud-api.prevu3d.com/oauth/token

ヘッダー：

Authorization: Basic <base64(client_id:client_secret)> — Client IDとSecretをclient_id:client_secretとしてエンコードし、その文字列をBase64エンコードします
Content-Type: application/x-www-form-urlencoded

ボディ： grant_type=client_credentials

リクエスト例：

POST https://cloud-api.prevu3d.com/oauth/token HTTP/1.1
Host: cloud-api.prevu3d.com
Authorization: Basic eW91ci1jbGllbnQtaWQ6eW91ci1jbGllbnQtc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

レスポンス例：

{
  "hasError": false,
  "expiresIn": 3600,
  "accessToken": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..."
}

レスポンスのaccessTokenを保存します。トークンは1時間有効です。その後は同じ方法で新しいトークンをリクエストする必要があります。

ステップ4：APIベースURLを取得する

リージョンRealityConnect API（組織は1つのリージョンを使用します。このガイドでは正確なURLの確認方法を説明します）：

組織のapiUrlを取得するには、以下の検出エンドポイントを呼び出してください。リージョンURLをハードコードしないでください。

エンドポイント： GET https://cloud-api.prevu3d.com/oauth/api-info

ヘッダー： Authorization: Bearer <your_access_token>

レスポンス例：

{
  "user": { "..." : "..." },
  "organization": {
    "id": "217ebd23-ec54-4af0-a6d6-4a441a6d1966",
    "name": "Test Organization"
  },
  "scopes": ["read:basic", "read:hierarchy"],
  "apiUrl": "https://api-ue1.prevu3d.com/realityconnect-api"
}

apiUrlの値をすべてのAPI呼び出しのベースとして使用します。organization.idもメモしておいてください。多くのエンドポイントで必要になります。

ステップ5：最初のAPI呼び出しを行う

必要なものはすべて揃いました。アクセストークンとベースURLです。組織のディビジョンを取得する簡単なリクエストを行いましょう：

GET {apiUrl}/v1/nodes/{organization_id}/browse
Authorization: Bearer <your_access_token>

実際の値を使用した例：

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/nodes/217ebd23-ec54-4af0-a6d6-4a441a6d1966/browse HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...

ディビジョンのリストを含む成功レスポンスは、統合が正しく機能していることを確認します。

Pythonで試す

上記のすべてを実行する完全なスクリプトです。client_idとclient_secretを認証情報に置き換えて実行してください。

import requests
import base64
import json

client_id = "your-client-id"
client_secret = "your-client-secret"
base_url = "https://cloud-api.prevu3d.com"

# ステップ1：トークンを取得
token_response = requests.post(
    f"{base_url}/oauth/token",
    data={"grant_type": "client_credentials"},
    headers={
        "Authorization": f'Basic {base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()}',
        "Content-Type": "application/x-www-form-urlencoded",
    },
)

token_response.raise_for_status()
access_token = token_response.json()["accessToken"]

# ステップ2：API URLと組織IDを取得
api_info = requests.get(
    f"{base_url}/oauth/api-info",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

api_url = api_info["apiUrl"]
organization_id = api_info["organization"]["id"]

# ステップ3：ディビジョンを参照
divisions = requests.get(
    f"{api_url}/v1/nodes/{organization_id}/browse",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

print("Divisions:", json.dumps(divisions, indent=2))

トラブルシューティング

表示される内容	試すこと
トークン取得時の401 Unauthorized	Client IDとSecretを再確認してください。`client_id:client_secret`を正しくBase64エンコードしていることを確認してください。
API呼び出し時の403 Forbidden	リクエストは3つのセキュリティレイヤーすべてを通過する必要があります。(1) OAuthアプリケーションに正しいスコープがあること、(2) サービスユーザーがターゲットノードへのコンテンツアクセスを持っていること、(3) そのノードに必要な権限を持つロールがあることを確認してください。

接続、DNS、API URLの問題については、セットアップ — API URLとネットワークアクセスを参照してください。

次のステップ

本番利用では、トークンの有効期限（1時間）が切れる前に更新するロジックを追加してください。
利用可能なすべての操作を確認するには、APIリファレンスを参照してください。