메인 콘텐츠로 건너뛰기
사용자가 귀하의 애플리케이션에 자신의 Ace Data Cloud 프로필, 서비스 구독, API Key, 사용량 또는 주문에 대한 접근 권한을 부여하도록 합니다. 표준 Authorization Code + S256 PKCE를 사용합니다. 애플리케이션이 인증 페이지를 열고, 사용자가 동의한 후 일회용 code를 받은 다음 OAuth access token으로 교환합니다. OAuth access token은 계정 리소스 인터페이스에 접근하는 데 사용됩니다. 모델 API를 호출하려면 해당 API Key를 사용합니다. OAuth 인증은 API Key를 자동으로 생성하거나, 서비스를 활성화하거나, 잔액을 추가하지 않습니다.

연동 방식 선택

표준 리디렉션에는 embed=studio, embed_origin 또는 postMessage가 필요하지 않습니다. Studio 컴포넌트 모드에서는 호스트가 인증 페이지를 생성하고 메시지 브리지를 유지합니다. 제3자는 본문 끝의 컴포넌트 프로토콜에 따라 연동하고, 이 두 매개변수를 직접 조합하지 마십시오.

엔드포인트 및 발견 문서

애플리케이션 관리 인터페이스에는 계정 로그인 인증이 필요하며, 익명 동적 등록(DCR) 인터페이스가 아닙니다. MCP 서비스 자체의 발견/등록 주소는 이 표의 계정 OAuth 엔드포인트와 다른 진입점입니다. 특정 MCP에 연결할 때는 해당 서비스의 문서와 발견 결과에 따라 작업하십시오. 발견 문서는 엔드포인트와 프로토콜 기능을 가져오는 데 사용됩니다. 현재 흐름은 OAuth token을 반환하며 id_token은 반환하지 않습니다. openid scope가 존재한다는 이유만으로 완전한 OpenID Connect 로그인 흐름으로 처리하지 마십시오.

권한 범위: 현재 scope 이름 사용

scope는 공백으로 구분되고 대소문자를 구별하는 권한 이름입니다. 새 애플리케이션은 profile:read, email:read, phone:read 등의 구체적인 권한을 사용합니다.

신청 가능한 권한을 가져오는 위치

로그인 후 OAuth 애플리케이션 목록 인터페이스 GET /api/v1/oauth2/applications/는 available_scopes를 반환합니다. 애플리케이션 관리 페이지의 권한 선택기도 동일한 카탈로그를 사용합니다. 이것이 일반 셀프서비스 애플리케이션이 사용해야 하는 선택 가능한 범위입니다. Discovery의 scopes_supported에는 플랫폼이 인식하는 모든 권한 이름이 포함되며, 귀하의 애플리케이션이 그중 모든 항목을 신청할 수 있음을 의미하지는 않습니다. 실제 인증에서는 다음을 동시에 확인합니다.
  1. 해당 권한이 이 애플리케이션 유형에 위임될 수 있는지;
  2. 해당 권한이 이 OAuth 애플리케이션의 허용 범위에 등록되어 있는지;
  3. 현재 사용자가 요청된 권한을 보유하고 있는지.
알 수 없거나, 등록되지 않았거나, 위임이 허용되지 않거나, 사용자가 보유하지 않은 권한은 invalid_scope를 반환합니다. 인증 코드 교환 및 갱신 시에도 다시 확인하며, 권한을 자동으로 보충하거나 상향하지 않습니다.

일반 셀프서비스 애플리케이션에서 선택 가능한 권한

다음은 현재 카탈로그(2026-10-09)이며, 연동 시에는 available_scopes를 기준으로 합니다. 예를 들어, 프로필만 읽으려면 profile:read를 사용하고, 이메일이 필요하면 email:read를 추가하며, 기존 API Key를 읽으려면 profile:read credentials:read를 사용합니다. 실제로 Key를 생성하거나 수정해야 할 때만 credentials:write를 신청하고, 갱신이 필요할 때 offline_access를 추가합니다. 일부 권한은 플랫폼이 승인한 신뢰할 수 있는 애플리케이션에만 제공됩니다. 예: sites:read, sites:write, platform-tokens:read; 다른 일부 권한은 일반 제3자 OAuth 애플리케이션에 공개되지 않습니다. 클라이언트 유형 public/confidential은 secret을 보관할 수 있는지 여부를 설명하며, 애플리케이션이 신뢰할 수 있는지와는 관련이 없습니다. 셀프서비스로 생성한 애플리케이션은 신뢰 권한을 직접 활성화할 수 없습니다. account는 지정된 공식 계정 관리 MCP에서 사용하는 계정 권한 선택기이며, 제3자 애플리케이션의 “모든 권한” scope가 아니므로 다른 scope와 혼용할 수 없습니다. 제3자는 필요한 구체적인 권한을 명확히 나열해야 합니다.

이전 문서에서 마이그레이션

이전 이름은 호환 별칭으로 허용되지 않습니다. OAuth 애플리케이션에 등록된 scopes, 인증 URL 및 자체 권한 판단을 함께 업데이트하십시오. 애플리케이션 구성을 수정해도 이미 발급된 token에 권한이 추가되지 않으며, 사용자가 다시 인증해야 합니다.

1단계: OAuth 애플리케이션 등록

OAuth 애플리케이션 관리를 열고 애플리케이션을 생성한 후 다음을 입력합니다:
  • 이름, 설명, 애플리케이션 Logo: 권한 부여 페이지의 애플리케이션 측에 표시됩니다.
  • 클라이언트 유형: 순수 프런트엔드, 모바일 또는 데스크톱 클라이언트는 Public을 선택합니다. 백엔드에서 secret을 보관할 수 있는 서비스는 Confidential을 선택합니다.
  • 콜백 주소: 프로덕션 환경에서는 HTTPS를 사용하고, 애플리케이션이 실제로 콜백을 처리하는 전체 URL을 등록합니다.
  • 권한: 페이지에서 제공하는 목록에서 실제로 필요한 scopes를 선택합니다.
client_id를 저장합니다. Confidential 클라이언트는 client_secret을 서버 측에 저장해야 하며, HTML, 프런트엔드 빌드 변수 또는 URL에 넣을 수 없습니다. Public 클라이언트는 token을 교환할 때 secret을 사용하지 않으며, 등록 응답에 해당 필드가 포함되어 있더라도 이를 클라이언트가 비밀로 유지할 수 있는 자격 증명으로 취급할 수 없습니다. redirect_uri는 등록, 권한 부여 및 token 교환 시 경로, 후행 슬래시 및 쿼리 매개변수를 포함하여 정확히 일치해야 합니다. 각 계정은 최대 20개의 애플리케이션을 만들 수 있습니다. Secret은 생성/교체 시에만 표시됩니다. 교체 후 이전 secret은 클라이언트 인증이 필요한 교환을 계속 수행할 수 없습니다.

2단계: 버튼으로 권한 부여 시작

연결을 클릭할 때마다 새로운 무작위 state와 code_verifier를 생성하고, 다음을 계산합니다:
state, verifier 및 콜백 주소를 애플리케이션 자체 세션에 저장한 뒤, URL 인코딩된 매개변수로 권한 부여 페이지를 엽니다:
Public 클라이언트는 반드시 S256 PKCE를 전송해야 합니다. Discovery에 여전히 plain이 나열되어 있더라도 Public 클라이언트는 이를 사용할 수 없습니다. Confidential 클라이언트도 S256 사용을 권장합니다. 권한 부여를 시작할 때 PKCE를 사용했다면 교환 시 해당 verifier를 반드시 제출해야 합니다. 사용자가 동의한 후 redirect_uri로 돌아오며, 쿼리 매개변수에는 code와 원본 그대로 반환된 state가 포함됩니다. 거부 시 error=access_denied, 오류 설명 및 state가 반환됩니다. 콜백을 처리하기 전에 state가 이번 세션과 일치하는지 먼저 확인합니다. 권한 부여 코드는 10분 동안 유효하며 한 번만 교환할 수 있습니다. 실패한 후에는 연결을 다시 시작해야 하며, 오래된 콜백 URL을 반복해서 새로고침하지 마십시오.

3단계: OAuth token 교환

Public 클라이언트는 브라우저 또는 클라이언트에서 직접 교환합니다. Confidential 클라이언트는 자체 백엔드에서 교환합니다. 요청 본문은 폼 인코딩을 지원하며, 다음 변수는 애플리케이션이 이번 권한 부여에서 얻은 데이터를 나타냅니다:
Confidential 클라이언트는 서버 측에서 client_secret 폼 필드도 추가해야 합니다. 현재 client_secret_post가 지원되며, HTTP Basic 클라이언트 인증을 이미 지원되는 방식으로 간주하지 마십시오. 성공 응답에서 access_token, token_type, expires_in 및 실제로 부여된 scope를 읽습니다. 요청하고 승인받은 경우에만 offline_access에 refresh_token이 있습니다. OAuth access token을 모델 API의 API Key로 취급하지 말고, token, verifier 또는 권한 부여 코드를 로그, 분석 이벤트 또는 공유 링크에 기록하지 마십시오.

4단계: 사용자 정보와 API Key 읽기

먼저 OAuth access token을 사용하여 UserInfo를 요청합니다:
반환 필드는 scope에 따라 달라집니다. id는 사용자 식별자입니다. profile:read 또는 openid로 기본 프로필(예: username, nickname, avatar, is_verified, date_joined, registration_method)을 읽을 수 있습니다. 이메일에는 email:read가 필요하며, 휴대전화 번호 및 지역에는 phone:read가 필요합니다. 권한이 부여되지 않은 필드가 항상 존재한다고 의존하지 마십시오. 기존 API Key가 필요하고 credentials:read가 승인된 경우, UserInfo의 id를 필터 조건으로 사용합니다:
반환 목록은 count와 items를 사용하며, Key 필드는 **items[*].token**이고 data[0].value가 아닙니다. user_id=me는 이 인터페이스에서 유효한 사용자 ID가 아닙니다. 여러 페이지의 데이터는 offset/limit로 계속 읽어야 하며, 첫 번째 페이지를 전체 자격 증명으로 간주하지 마십시오. 애플리케이션, 서비스 및 유효 상태에 따라 적용 가능한 자격 증명을 선택하고, 무작정 첫 번째 항목을 가져오지 마십시오. 목록이 비어 있다고 해서 권한 부여 실패를 의미하지는 않습니다. 사용자가 아직 적용 가능한 Key를 생성하지 않았을 수 있습니다. OAuth access token의 권한 제어와 API Key 자체의 서비스 범위, 할당량 및 만료 조건은 서로 다른 제약입니다. API Key 읽기를 허용한다는 것은 제3자가 이를 저장하고 사용할 수 있음을 의미합니다. OAuth 요청을 철회하거나 애플리케이션 로그인 상태를 삭제해도 이미 복사된 API Key는 무효화되지 않습니다. 사용자는 자격 증명 관리에서 해당 Key를 별도로 철회하거나 교체해야 합니다.

실행 가능한 Public / PKCE 브라우저 예제

다음 페이지를 등록한 REDIRECT_URI에 배포하고, CLIENT_ID와 콜백 주소를 교체합니다. 버튼은 표준 권한 부여를 시작하며, 동일한 페이지로 돌아온 후 개인 프로필과 기존 Key 수를 읽습니다. 예제는 Key를 표시하거나 영속화하지 않습니다. 프로덕션 애플리케이션은 실제 용도에 따라 결과를 사용합니다. 먼저 독립 브라우저 페이지에서 검증한 다음, 이후의 iframe 요구 사항에 따라 검수합니다.
예시의 콜백과 진입점은 이전에 저장한 sessionStorage를 읽을 수 있도록 반드시 동일한 출처, 동일한 브라우저 탭/iframe에 있어야 합니다. 프로덕션 애플리케이션은 자체 세션 방식으로 토큰을 관리하고 만료를 처리하며, 응답을 받은 후 권한 부여 URL 매개변수를 제거해야 합니다. 페이지의 주 인터페이스는 먼저 렌더링되어야 하며, 네트워크 실패는 연결 상태에만 영향을 주어야 합니다.

화이트 라벨 웹사이트의 iframe

고객 웹사이트가 직접 권한 부여 페이지로 이동

표준 OAuth 매개변수와 자체 콜백 처리만 사용하면 됩니다. window.location.assign()은 현재 iframe을 탐색하며, 부모 페이지는 화이트 라벨 도메인에 유지됩니다. 아이콘을 위해 embed=studio를 추가하거나 Studio 메시지 프로토콜을 구현할 필요가 없습니다. 다음 조건을 충족해야 합니다:
  • 애플리케이션 페이지와 콜백 페이지는 HTTPS를 사용하고 실제로 접근 가능하며, 화이트 라벨 부모 도메인이 iframe을 통해 임베드할 수 있도록 허용해야 합니다. 양쪽의 Content-Security-Policy: frame-ancestors 및 X-Frame-Options를 확인합니다.
  • sandbox는 페이지에 필요한 스크립트, 양식 및 출처/저장소 기능을 허용해야 합니다. 팝업 로그인을 지원할 때는 해당 팝업 기능도 필요합니다. Studio에서 제공하는 Website 컴포넌트 구성을 우선 사용합니다.
  • 브라우저는 현재 임베드 시나리오에서 권한 부여 상태에 필요한 저장소 사용을 허용해야 합니다. 화이트 라벨 사이트의 로그인 상태와 AuthFrontend의 로그인 상태는 다를 수 있으므로, 화이트 라벨 사이트에 로그인했다고 해서 권한 부여 페이지에도 이미 로그인되어 있다고 가정해서는 안 됩니다.
  • 콜백의 token 교환 서비스는 사용 가능해야 하며, 교차 출처 요청은 애플리케이션 출처를 허용해야 합니다. DNS, CORS, HTTP 오류는 모두 재시도 가능한 상태로 표시되어야 하며, 전체 페이지의 렌더링이 중단되어서는 안 됩니다.
권한 부여 페이지의 왼쪽은 OAuth 애플리케이션 Logo를 읽습니다. 오른쪽은 브라우저가 부모 출처를 제공할 수 있고 부모 도메인이 검증된 사이트 검증을 통과한 경우 해당 Site의 favicon/logo를 읽으며, 그렇지 않으면 기본 아이콘을 표시합니다. 이는 브랜드 표시만 결정할 뿐 로그인 세션을 생성하지 않으며, 고객 페이지에 계정 권한을 제공하지도 않습니다. 현재 제한 사항: iframe 내부에서 일반 OAuth가 재로그인을 요구하는 경우, 로그인 완료 후 계속해서 권한 부여 페이지로 돌아가는 흐름에는 아직 공백이 있습니다. 출시 전에 반드시 “Auth 로그인됨”과 “Auth 로그인되지 않음/만료됨”을 각각 검수해야 합니다. 이 공백이 수정되고 검증되기 전에는 최초 로그인을 별도 페이지에서 표준 OAuth로 완료하거나, 아래의 Studio 컴포넌트 권한 부여를 사용하세요. 로그인된 테스트 결과만으로 모든 iframe 시나리오가 사용 가능하다고 약속하지 마세요.

Studio의 현재 계정을 사용한 권한 부여

Studio의 「설정 → 홈 → 웹사이트 컴포넌트」에서 OAuth를 활성화하고, client_id와 등록된 콜백 주소를 입력합니다. 웹사이트와 콜백은 동일한 HTTPS 출처를 사용해야 하며, Studio 출처와는 달라야 합니다. 타사 페이지는 다음이 필요합니다:
  1. 정확한 부모 사이트 origin으로 acedatacloud:oauth:ready를 전송하고, acedatacloud:oauth:init를 수신하고 검증합니다.
  2. 버튼이 state와 PKCE verifier를 생성하고, acedatacloud:oauth:authorize(state, S256 challenge)를 전송합니다. verifier는 자체 페이지 내부에 보관합니다.
  3. 부모 창, origin 및 state를 검증하고, acedatacloud:oauth:result의 code 또는 error를 처리한 후 표준 token 엔드포인트에서 교환합니다. Studio는 컴포넌트 영역에 권한 부여 페이지를 표시하며, 사용자가 동의한 후 메시지로 권한 부여 코드를 반환하고, 애플리케이션은 리디렉션할 필요가 없습니다. 로그인되어 있지 않을 때는 login_required를 반환하고, 거부 시에는 access_denied를 반환하며, 대기 시간 초과 시에는 authorization_timeout을 반환합니다. 계정 변경은 애플리케이션 iframe을 다시 생성하고 완료되지 않은 권한 부여를 취소합니다.
컴포넌트는 현재 profile:read credentials:read를 요청하며, offline_access를 포함하지 않습니다. refresh token을 반드시 받을 수 있다고 가정하지 마십시오. embed=studio, embed_origin은 Studio 호스트와 권한 부여 페이지에서 관리하며, 고객 페이지는 메시지 프로토콜만 준수하면 됩니다. 전체 버튼 예시는 Studio 웹 컴포넌트 OAuth 연동 가이드를 참조하십시오.

수명 주기, 갱신 및 철회

Access token의 기본 유효 기간은 15일이며, 매 응답의 expires_in을 기준으로 갱신 또는 재권한 부여를 계획해야 합니다. refresh token의 기본 유효 기간은 30일이며, 기간은 서비스 설정의 영향을 받습니다. 이 두 값을 영구적인 약속으로 하드코딩하지 마십시오. offline_access 권한을 받은 후 다음을 호출할 수 있습니다:
갱신은 새 token을 반환하며, 애플리케이션은 최신 값을 저장해야 합니다. 갱신 시 애플리케이션이 여전히 유효한지, 사용자가 사용 가능한지, 권한이 여전히 허용되는지를 확인합니다. 실패 시 자체 연결 상태를 지우고 다시 권한을 부여하십시오. 현재 OAuth 갱신 구현은 이전 refresh token이 갱신 후 즉시 무효화됨을 보장하지 않습니다. 새 token을 받았다고 해서 이전 token이 철회되었다고 간주하지 말고, secret을 교체하는 것으로 기존 token의 종료를 대체하지 마십시오. 철회 요청의 호출 방식은 다음과 같습니다:
현재 철회 엔드포인트는 HTTP 200을 반환하지만, 이미 발급된 JWT의 즉각적인 무효화를 구현하지 않습니다. 애플리케이션은 자체적으로 저장한 token을 지워야 하며, 200을 모든 발급된 token 또는 API Key가 무효화되었다는 증거로 간주해서는 안 됩니다. 유출되었거나 복제된 API Key와 관련된 경우에는 해당 자격 증명을 별도로 철회하거나 교체해야 합니다.

일반적인 오류 및 검수

배포 전에 최소한 다음을 검증하십시오: 올바른 콜백, 거부, 잘못된 state, 만료/이미 사용된 code, Key 없음, 네트워크 실패, token 만료, 필요한 scope 누락, 그리고 iframe 환경에서의 최초 로그인과 계정 전환. 테스트 증거에 전체 code, token 또는 API Key를 저장하지 마십시오.

2단계 인증 및 재권한 부여

사용자가 2단계 인증을 활성화한 후, Ace Data Cloud는 권한 부여 페이지에서 인증기 인증 코드 또는 일회용 복구 코드 검증을 완료한 다음 권한 부여 코드를 전달합니다. 귀하의 애플리케이션은 계속 표준 OAuth 흐름을 사용해야 하며, 사용자에게 인증기 키 및 복구 코드를 요청하거나 저장하거나 전달해서는 안 됩니다. 사용자가 2단계 인증을 활성화, 변경, 비활성화하거나 계정을 복구한 후에는 이전 계정 세션, 갱신 토큰 및 관련 플랫폼 권한 부여 토큰이 무효화될 수 있습니다. 유효하지 않은 세션 또는 invalid_grant를 받으면 사용자에게 표시되는 권한 부여 흐름을 다시 시작하십시오. 이전 권한 부여 코드를 반복해서 사용하지 말고, 검증을 우회하려고 시도하지 마십시오. 일반 모델 API Key의 인증 방식은 그대로 유지됩니다. 계정 탈취가 의심되는 경우에는 영향을 받은 API Key를 별도로 확인하고 철회해야 합니다.