Cloudflare AI Gateway 인증 필수화: 새 게이트웨이만 실패할 때 확인할 것

AI 요청이 인증된 통로를 거치는 모습을 표현한 생성형 개념 이미지다. 실제 Cloudflare 화면은 아니다.

같은 코드가 기존 AI Gateway에서는 동작하지만 새로 만든 게이트웨이에서는 실패할 수 있다. Cloudflare가 2026년 11월 3일부터 새 AI Gateway에 인증을 필수로 적용했기 때문이다. 해결 순서는 요청 주소와 인증 헤더를 먼저 확인하고, 클라이언트를 준비한 뒤 게이트웨이 설정을 바꾸는 것이다.

새 게이트웨이와 기존 게이트웨이를 나눠 본다

공식 변경 공지는 다음 세 가지를 구분한다.

새 게이트웨이 생성 시 인증은 기본으로 켜진다. authentication을 생략하거나 true로 설정할 수 있지만 false는 HTTP 400을 반환한다.

기존 게이트웨이 수정 시 필드를 생략하면 현재 값이 유지된다. 이미 인증이 켜졌다면 다시 끌 수 없다.

기존에 인증이 꺼진 게이트웨이는 계속 사용할 수 있다. 모든 기존 게이트웨이가 즉시 강제 전환된다는 뜻은 아니다.

따라서 예전 자동화에 들어 있는 "authentication": false를 그대로 복사해 새 환경을 만들면 생성 단계부터 실패할 수 있다. 인증을 켠 뒤 문제가 생겼을 때도 스위치를 끄는 방식의 복구를 기대하면 안 된다. 11월 3일 공식 변경 공지

요청 주소에 따라 헤더가 달라진다

Cloudflare REST API의 api.cloudflare.com 경로는 Authorization을 사용한다. 기존 provider-native 경로인 gateway.ai.cloudflare.com에는 게이트웨이 인증용 cf-aig-authorization을 보낸다. 공급자 자체 인증이 필요한 경로에서는 그 인증도 별도로 유지해야 한다.

Worker의 바인딩을 통한 호출은 연결된 계정 안에서 사전 인증된다. HTTP 클라이언트와 같은 방식으로 게이트웨이 헤더를 수동 추가한다고 가정하지 않는다. 인증 문서, Workers 바인딩 문서

권한 이름도 주소와 함께 확인해야 한다. 현재 REST API 문서는 /accounts/{account_id}/ai/*에 Account > Workers AI > Read 권한을 요구하며, AI Gateway 권한만 있는 토큰은 401과 오류 코드 10000을 받을 수 있다고 설명한다. 게이트웨이 설정을 관리하는 API와 모델을 실행하는 API를 같은 권한으로 취급하지 않는 것이 중요하다. REST API 인증 설명

네트워크 호출 없이 헤더 분기를 먼저 검사한다

다음 코드는 이 글에서 만든 로컬 예제다. 토큰 발급이나 모델 호출을 하지 않고, 허용한 HTTPS 주소에 맞는 헤더만 만든다. 완성된 HTTP 클라이언트나 공급자 인증 구현은 아니다.

가짜 값 TEST_ONLY로 두 정상 주소의 헤더를 확인하고, HTTP 주소·다른 호스트·유사 호스트 세 가지를 거부하는 총 5개 로컬 검사를 실행해 통과했다. 실제 Cloudflare 계정 권한이나 모델 응답을 검증한 결과는 아니다.

운영 코드에서는 이 예제만으로 보안 검증을 끝내지 않는다. 리다이렉트 대상에 인증 헤더가 넘어가지 않도록 HTTP 라이브러리 동작을 확인하고, 로그에서 두 인증 헤더 값을 모두 가린다. 토큰은 브라우저 번들이나 공개 저장소에 넣지 않는다.

전환은 클라이언트 준비부터 시작한다

다음 순서는 공식 변경사항을 바탕으로 제안하는 운영 점검 절차다.

배치 작업, 서버, 개발 도구가 사용하는 실제 요청 호스트와 경로를 목록으로 만든다.

각 경로가 요구하는 헤더와 토큰 권한을 확인한다. 자격증명 값 자체는 점검표에 기록하지 않는다.

별도 검증 환경에서 클라이언트 설정을 준비하고, 성공 요청뿐 아니라 인증 누락이 차단되는지도 확인한다.

기존 게이트웨이에 인증을 켜기 전 모든 호출자의 전환 여부를 확인한다.

변경 후에는 애플리케이션 오류와 게이트웨이 인증 오류를 구분해 관찰한다.

실제 모델 요청에는 비용이 발생할 수 있으므로 사전에 정한 테스트 예산과 비민감 입력을 사용한다. 이 글에서는 유료 API 테스트나 계정 설정 변경을 실행하지 않았다.

토큰 하나가 게이트웨이 하나만 여는 것은 아니다

인증 문서는 AI Gateway의 Read·Run·Edit 권한이 계정 범위이며, 단일 게이트웨이로 제한되지 않는다고 설명한다. 특히 Run 권한은 같은 계정의 다른 게이트웨이와 저장된 공급자 키 사용에도 영향을 줄 수 있다. 테넌트별 격리를 설계한다면 별도 계정이나 Worker 측 바인딩 구조를 검토해야 한다. 토큰 범위 안내

이번 변경의 핵심은 기본값 하나가 아니다. 생성 설정, 호출 헤더, 실행 권한, 복구 계획을 함께 맞추는 것이 이전 작업의 단위가 된다. 새 환경만 실패한다면 모델 이름부터 바꾸기보다 이 네 항목을 먼저 비교하는 편이 원인을 좁히기 쉽다.