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 (조직은 하나의 지역을 사용합니다; 이 가이드에서 정확한 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"
}

모든 API 호출의 기본으로 apiUrl 값을 사용합니다. 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"

# Step 1: Get a token
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"]

# Step 2: Get your API URL and org 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"]

# Step 3: Browse divisions
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	요청은 세 가지 보안 계층을 모두 통과해야 합니다. (1) OAuth 애플리케이션에 올바른 스코프가 있는지, (2) 서비스 사용자가 대상 노드에 대한 콘텐츠 접근 권한이 있는지, (3) 해당 노드에 필요한 권한이 있는 역할을 가지고 있는지 확인하세요.

연결, DNS, API URL 문제는 시작하기 — API URL 및 네트워크 접근을 참조하세요.

다음은?

토큰이 만료되기 전에(1시간 후) 새로 고치는 로직을 추가하세요.
사용 가능한 모든 작업을 보려면 API 참조를 살펴보세요.