Authorization Code + Custom Redirect 플로

로그인한 사용자를 대신하여 작동하고 자체 도메인에서 OAuth 콜백을 수신하는 웹 애플리케이션에는 Authorization Code + custom HTTPS redirect 플로를 사용하세요. 이는 PKCE를 사용한 Authorization Code, 정확히 일치하는 HTTPS 리디렉션 URI, 기밀 서버 측 클라이언트를 위한 선택적 클라이언트 시크릿을 사용합니다.

전제 조건, 네트워크 접근, 보안 모델을 아직 다루지 않았다면 먼저 시작하기 가이드를 검토하세요.

수행할 작업

OAuth 애플리케이션 생성: HTTPS 콜백 URL과 함께 Prevu3D에 웹 앱을 등록합니다
사용자 접근 구성: 로그인하는 사용자가 필요한 데이터에 도달할 수 있는지 확인합니다
PKCE로 인증: 브라우저 동의 페이지를 통해 사용자를 보냅니다
코드를 토큰으로 교환: 인증 코드를 액세스 토큰으로 교환합니다
API URL 찾기: 조직의 기본 URL을 검색합니다(지역에 따라 다릅니다)
첫 호출하기: 간단한 요청으로 연결을 테스트합니다

1단계: OAuth 애플리케이션 생성

Prevu3D Platform에 로그인합니다.
Settings → OAuth로 이동합니다.
클릭하여 새 애플리케이션을 생성합니다.
Authorization Code flow를 활성화합니다.
Native Application을 끈 상태로 둡니다.
Redirect URI를 입력합니다, 예: https://app.example.com/oauth/callback. 완전히 정규화된 도메인 이름과 함께 HTTPS여야 하며 인증과 토큰 교환 시 정확히 일치해야 합니다.
앱이 서버 측에 저장할 수 있는 경우 선택적으로 클라이언트 시크릿을 활성화합니다. 공개 브라우저 전용 클라이언트는 시크릿을 사용하지 않아야 합니다.
Client ID(및 생성된 경우 시크릿)를 복사하고 안전하게 저장합니다.

2단계: 사용자 접근 구성

이 플로는 서비스 사용자가 아닌 로그인한 사용자로서 API를 호출합니다. 이는 보안 모델의 계층 2와 3을 다룹니다: 사용자가 볼 수 있는 노드(콘텐츠 접근)와 그것으로 할 수 있는 작업(역할/권한 접근).

로그인할 사용자가 사용 사례에 필요한 노드(조직, 디비전, 사이트 등)에 대한 콘텐츠 접근 권한이 있는지 확인하세요.
사용자가 연동에 필요한 권한(읽기, 편집, 관리 등)이 있는 해당 노드에 대한 역할을 가지고 있는지 확인하세요.

동의 화면에서, 사용자는 승인할 조직도 선택합니다. 사용자가 거기서 승인하는 스코프는 계층 1을 구성합니다.

3단계: PKCE로 인증

동의 페이지를 열기 전에, 세 가지 값을 생성하세요:

값	방법
`code_verifier`	무작위 문자열, 43~128자
`code_challenge`	패딩 없는 `BASE64URL(SHA256(code_verifier))`
`state`	무작위 문자열; 리디렉션이 돌아올 때 검증

사용자의 브라우저를 동의 페이지로 엽니다.

동의 URL: https://cloud.prevu3d.com/oauth

쿼리 매개변수 (모두 필수):

매개변수	값
`response_type`	`code`
`code_challenge_method`	`S256`
`client_id`	Client ID
`redirect_uri`	등록된 HTTPS 콜백 URI(정확히 일치, 등록된 경우가 아니면 후행 슬래시 없음)
`scopes`	스코프당 하나, 예: `scopes=read:basic&scopes=read:hierarchy`
`code_challenge`	위의 PKCE 챌린지
`state`	무작위 state 값

사용자가 로그인하고 Allow를 클릭하면, 브라우저가 콜백으로 리디렉션됩니다:

https://app.example.com/oauth/callback?code={authorization_code}&state={state}

사용자가 접근을 거부하면, 대신 ?error=access_denied를 받습니다. 인증 코드는 60초 후에 만료되므로, 즉시 교환하세요.

4단계: 코드를 액세스 토큰으로 교환

엔드포인트: POST https://cloud-api.prevu3d.com/oauth/token

헤더: Content-Type: application/x-www-form-urlencoded

본문:

필드	값
`grant_type`	`authorization_code`
`client_id`	Client ID
`code`	리디렉션의 코드
`redirect_uri`	3단계에서 사용한 동일한 URI
`code_verifier`	원래 PKCE verifier
`client_secret`	앱에 시크릿이 있는 경우에만

client_id와 client_secret을 본문에 보내거나 Authorization: Basic base64(client_id:client_secret)을 사용할 수 있습니다.

예제 응답:

{
  "hasError": false,
  "expires_in": 86400,
  "access_token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "..."
}

두 토큰을 모두 저장합니다. API 호출에는 access_token을 사용합니다. 만료되면, grant_type=refresh_token과 저장된 refresh_token으로 새 토큰을 요청합니다.

5단계: 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도 기록해 두세요.

6단계: 첫 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...

디비전 목록을 포함하는 성공적인 응답은 연동이 올바르게 작동하고 있음을 확인합니다.

문제 해결

증상	확인할 사항
동의 또는 토큰 교환 시 Redirect URI mismatch	`redirect_uri`는 OAuth 앱에 등록된 값과 문자 하나하나 일치해야 합니다
앱 저장 시 Invalid OAuth redirect URI	등록된 URI에 `https`, 유효한 도메인 이름을 사용하고, 쿼리 문자열이나 프래그먼트가 없어야 합니다
Bad OAuth application secret	앱이 시크릿과 함께 생성된 경우에만 `client_secret`을 포함하세요
Grant exchange expired	인증 코드는 60초 후에 만료됩니다; 플로를 다시 시작하세요
RCAPI 호출 시 403	사용자에게 작업에 대한 콘텐츠 접근, 노드 역할, OAuth 스코프가 없을 수 있습니다

데스크톱 앱이나 CLI를 위한 루프백 리디렉션이 필요하신가요? 대신 Native Application 플로를 사용하세요.

다음은?

사용자 지정 도메인 없이 localhost / PKCE를 위한 Native Application 플로
서버 대 서버 접근을 위한 Client Credentials 플로
전체 엔드포인트 카탈로그를 위한 대화형 API 참조