> 한줄 요약: 연결 표시만 믿지 않고 connected → identity → scope → read call을 분리해 확인하면, 재설치 없이도 읽기 권한 문제를 좁힐 수 있다.
---
바쁘시면 이것만 보세요
connected는 연결 객체가 있다는 뜻이다.identity성공은 현재 주체를 확인했다는 뜻이다.scope는 대상 API에 허용된 권한 범위다.read call성공이 실제 읽기 가능 상태를 증명한다.인증 진단에 생성·수정·삭제를 사용하지 않는다.
계정 선택, 추가 인증, 동의는 사용자가 직접 수행한다.
---
이런 분께 추천합니다
외부 API 연결은 보이는데 데이터 읽기만 실패하는 분
로그인 성공과 업무 권한을 같은 상태로 취급하고 있는 분
인증 오류가 나면 곧바로 커넥터를 재설치하는 분
외부 데이터를 변경하지 않고 권한을 검증하고 싶은 분
---
문제: 연결 표시는 정상이지만 읽기 호출은 실패했다
OAuth 기반 연동에서는 다음 상태가 동시에 성립할 수 있다.
| 계층 | 확인 대 상 | 해석 | |---|---|---| | connected | 연결 객체 존재 | 연동 설정이 존재함 | | identity | 주체 확인 호출 | 인증된 주체를 식별할 수 있음 | | scope | 승인된 권한 범위 | 대상 API 권한이 포함됐는지 확인 필요 | | read call | 대표 읽기 호출 | 실제 업무 경로의 접근 가능 여부 |
identity가 성공해도 대상 데이터의 읽기 권한이 보장되지는 않는다. 따라서 전체를 “로그인 문제”로 묶지 않고 마지막으로 성공한 계층과 처음 실패한 계층을 찾아야 한다.
---
사용한 도구
연결 상태 조회 기능
OAuth 권한 범위 확인 기능
읽기 전용 API 호출
대상 에이전트의 도구 실행 결과
새 구성요소를 만들기보다 기존 연동을 읽기 전용으로 점검하는 방식이다.
---
작업 과정
### 1. 네 상태를 따로 기록했다
connected: 확인/미확인
identity: 성공/실패/미검증
scope: 충분/부족/미검증
read call: 성공/실패/미검증이 표만으로 연결 부재, 주체 확인 실패, 권한 부족, 실제 API 실패를 서로 다른 문제로 다룰 수 있다.
### 2. 실제로 실패한 읽기 호출을 기준으로 범위를 좁혔다
관리 화면의 정상 표시보다 대상 에이전트가 사용하는 대표 읽기 호출을 우선했다. 오류가 권한 계층을 가리키면 설치나 라우팅을 먼저 바꾸지 않는다.
### 3. 최소 권한 재동의를 검토했다
연결과 주체 확인이 살아 있다면 전체 삭제보다 필요한 읽기 범위를 포함한 재동의를 우선 검토한다. 동의 화면에서 계정 선택과 승인 행위는 사용자가 직접 수행한다.
### 4. 쓰기 없는 동일 경로로 재검증했다
복구 확인은 관리 화면이 아니라 대상 에이전트의 같은 종류 읽기 호출로 수행한다. 생성·수정·삭제 호출은 별도 승인 전까지 실행하지 않는다.
---
결과: Before / After
| 구분 | Before | After | |---|---|---| | connected | 확인 | 확인 | | identity | 성공 가능 | 성공 가능 | | scope | 읽기 범위 부족 또는 미확인 | 필요한 읽기 범위 확인 | | read call | 실패 | 성공 여부를 실제 호출로 판정 | | write call | 실행하지 않음 | 실행하지 않음 |
핵심 결과는 특정 서비스의 복구 수치가 아니라, 연결·주체·권한·실제 호출을 독립된 검증 항목으로 만든 것이다.
---
배운 팁
### 1. Identity는 업무 권한 증명 이 아니다
주체를 확인하는 호출과 업무 데이터를 읽는 호출은 필요한 권한이 다를 수 있다.
### 2. 가장 작은 실제 호출로 검증한다
목록이나 메타데이터처럼 부작용 없는 읽기 호출을 대표 검증으로 사용한다.
### 3. 미검증을 성공으로 바꾸지 않는다
읽기 성공은 쓰기 권한이나 다른 API의 정상 상태를 증명하지 않는다.
### 4. 사용자 통제 구간을 분리한다
로그인, 추가 인증, 계정 선택, 권한 동의는 자동화하지 않고 사용자에게 넘긴다.
---
다른 업무에 적용한다면
파일, 메일, 문서, 협업 API도 같은 순서로 점검할 수 있다.
connected
→ identity
→ scope
→ representative read call
→ 대상 에이전트에서 재검증쓰기 기능은 읽기 복구와 분리해 별도 승인과 별도 시험으로 다룬다.
---
재사용 프롬프트
OAuth 기반 외부 API 연결은 보이지만 읽기 호출이 실패한다.
읽기 전용으로 다음을 진단해줘.
1. connected, identity, scope, read call을 별도 상태로 기록한다.
2. 마지막 성공 계층과 첫 실패 계층을 찾는다.
3. identity 성공을 대상 데이터 접근 성공으로 간주하지 않는다.
4. 권한 부족이면 재설치보다 필요한 최소 읽기 범위의 재동의를 우선 검토한다.
5. 로그인, 추가 인증, 계정 선택, 동의는 사용자가 직접 수행하게 멈춘다.
6. 복구 후 대상 에이전트에서 같은 종류의 읽기 호출을 재실행한다.
7. 생성·수정·삭제는 실행하지 않는다.
8. 성공, 실패, 미검증 항목을 분리해 보고한다.
9. 자격증명, 계정 정보, 실제 데이터 내용은 출력하지 않는다.---
공개 전 점검
[x] 주체와 대상 데이터의 식별정보를 포함하지 않았다.
[x] 실제 데이터 내용을 포함하지 않았다.
[x] 자격증명과 인증 코드를 포함하지 않았다.
[x] connected, identity, scope, read call을 분리했다.
[x] 읽기 검증을 쓰기 권한 검증으로 과장하지 않았다.
[x] 공개 기술 설명에 필요하지 않은 식별 단서를 포함하지 않았다.
[x] 외부 게시를 수행하지 않았다.
