권한이 실패했다는 메시지를 받으면 다시 누르고 싶어진다. 내 작업에서도 배포와 DNS 연결, 검색 소유권 확인이 서로 다른 권한 문제인데 한 덩어리처럼 보이곤 했다.
공용 키 보관 안내에는 과거 토큰의 만료와 다른 인증 경로를 사용했던 기록이 남아 있었다. 2026년 10월 이번 임시 사이트는 별도의 관리용 API 자격증명으로 Pages 배포를 완료했다. 과거의 인증 방식이 지금도 유효하다고 전제할 수 없었다.
내가 필요한 권한의 범위를 적는 이유
나는 수정을 맡길 때 내 사이트를 고칠 수 있는 권한은 주고 싶다. 동시에 관계없는 사이트까지 건드리는 상황은 만들고 싶지 않다. 그래서 작업 목표와 허용 범위를 먼저 적고 그 범위에서 성공했는지 확인한다.
같은 로그인으로 모든 작업이 되는 것은 아니다
브라우저 로그인, API 토큰, 계정 선택은 서로 다른 확인 항목이다. 조회 권한이 있다는 사실로 DNS 수정이나 Pages 배포 권한까지 증명하지 않는다. 공식 문서에서 필요한 권한과 대상 리소스 범위를 확인한다.
내가 쓰는 진단 순서
- 실패한 동작을 조회, 배포, DNS 변경, 외부 서비스 소유권 확인 중 하나로 적는다.
- 응답 코드와 오류 코드를 기록한다. 키와 인증 헤더를 로그에 남기지 않는다.
- 대상 계정과 프로젝트가 맞는지 읽기 전용 요청으로 확인한다.
- 토큰의 상태, 필요한 권한, 리소스 범위를 대조한다.
- 성공했던 경로와 실패한 경로를 분리하고, 원인이 좁혀진 뒤 같은 요청을 다시 실행한다.
공개해도 되는 기록과 남기지 않을 값
작업명, 대상 리소스 종류, 오류 코드, 확인 시점은 운영 지식이 된다. 실제 토큰, 쿠키, 개인 계정 정보는 지식 공개에 필요하지 않다. 예제에는 읽어야 할 변수 이름만 남기고 값을 넣지 않는다.
토큰 검증에 성공해도 특정 프로젝트의 쓰기 권한은 별도로 확인한다. 권한을 무조건 넓히는 것은 문제의 원인을 이해하는 방법이 아니다.
코드와 구현 살펴보기
토큰 값을 출력하지 않는 PowerShell 예시
$cfHeaders = @{ Authorization = 'Bearer ' + $env:CLOUDFLARE_API_TOKEN }
$check = Invoke-RestMethod -Uri ($cfApiBase + '/user/tokens/verify') -Headers $cfHeaders
$check.result.status완료라고 적는 시점
원래 실패했던 작업이 의도한 리소스에서 성공하고, 그 결과를 다시 조회해 확인한 뒤 완료로 적는다. 인증 성공과 기능 성공을 구별하면 재시도가 줄고 다음 사람이 같은 상황을 더 빨리 이해한다.