AI 에이전트 API 키 인증 실패 — 자리표시자가 그대로 나갑니다

AI 에이전트에 키를 분명히 등록했는데 인증 실패가 뜨는 경우가 있습니다. 오타도 아니고 만료도 아닌데요. 공식 문서를 읽다가 원인 하나를 찾았습니다 — 진짜 값 대신 넣어둔 가짜 문자열이 치환되지 않고 그대로 나간 것입니다. 대표적인 게 헤더에만 넣도록 돼 있는데 본문으로 보내는 경우예요. 어디서 갈리는지, 그리고 아예 안 되는 방식은 뭔지 정리했습니다.

📌 30초 요약

• ★막힌 자리에서는 치환도 제거도 안 됩니다 — 가짜가 그대로 전송.
• ⚠️ 콘솔에서 만들면 헤더만 켜집니다.
• 본문으로 보내는 방식이면 따로 켜줘야 합니다.
• ★키로 토큰을 받아오는 방식은 안 가려집니다.
• 서명을 계산하는 방식도 실패합니다.
• ⚠️ 작업공간 권한이 있으면 누구나 참조할 수 있습니다.

키를 넣었는데 인증 실패가 뜬다면

동작 방식부터 짚으면 이렇습니다. 실제 값은 작업 공간 안에 들어가지 않고 알아볼 수 없는 가짜 문자열이 대신 놓입니다. 그러다 바깥으로 요청이 나갈 때 그 자리에서 진짜 값으로 바뀌어 나가요. 키 자체를 안 쓰는 방식과는 다른 접근인데, 어쨌든 모델은 진짜 값을 못 봅니다.

⚠️ 안 바뀌면 지워지지도 않습니다

문제는 치환이 일어나지 않는 자리입니다. 문서가 분명히 적어뒀어요 — 막힌 위치의 가짜 문자열은 바뀌지도, 지워지지도 않고 글자 그대로 상대 서비스에 전송됩니다. 받는 쪽은 당연히 이상한 값이 왔다며 인증을 거절하고요. 그래서 상대가 보낸 오류만 보면 "키가 틀렸나" 싶지만 실제로는 키가 아니라 자리가 문제입니다.

헤더냐 본문이냐가 갈림길입니다

치환할 자리를 요청 머리말과 요청 몸통, 두 곳으로 나눠 지정할 수 있습니다. 여기서 사고가 납니다.

만든 방식	켜지는 자리
관리 화면에서 생성	머리말만 — 몸통은 꺼짐
자리 지정을 아예 생략	둘 다 켜짐
한쪽만 적어서 생성	적은 쪽만 — 나머지는 자동으로 꺼짐
나중에 수정	적은 항목만 바뀌고 나머지는 유지

그래서 관리 화면에서 만들어놓고 몸통에 담아 보내는 방식을 쓰면 조용히 실패합니다. 로그인 정보를 폼 형태로 실어 보내는 요청이 대표적이에요. 문서도 이 경우를 콕 집어 몸통 쪽을 따로 켜라고 안내합니다. 참고로 둘 다 끄는 건 애초에 거부되고, 빈 값을 넣는 것도 오류입니다 — "항목 자체를 빼라"는 게 문서의 표현이에요.

그럼 어느 쪽이 안전할까요. 문서는 머리말만 켜는 쪽이 더 좁은 설정이라고 봅니다. 요청 몸통은 에이전트가 다루던 내용으로 조립되는 경우가 많아 노출 면이 넓거든요. 대부분의 서비스가 머리말에서 키를 읽으니 기본은 그쪽으로 두는 게 맞습니다.

교환해서 받아온 토큰은 안 가려집니다

이 방식이 아예 안 통하는 경우도 문서가 정리해뒀습니다. 핵심은 바꿔치기가 나가는 길목에서만 일어난다는 점이에요. 안에서 값을 만지는 순간에는 가짜 그대로입니다.

🚫 이런 방식은 실패합니다

시작할 때 키 형식을 검사하는 도구는 가짜를 보고 거절합니다. 키로 서명을 계산하는 방식도 엉뚱한 서명이 만들어지고요. 그리고 하나 더 중요한 게 — 저장된 키로 세션 토큰을 받아오는 흐름입니다. 받아온 토큰은 가려지지 않은 채로 작업 공간에 들어옵니다. 이럴 땐 교환을 내가 직접 해서 결과 토큰을 대신 등록하라는 게 문서의 권고입니다.

정리하면 보낸 값을 그대로 실어 보내는 방식에만 통합니다. 한 가지 더, 에이전트가 일할 환경을 설계할 때 놓치기 쉬운데 — "이 키를 어느 주소로 나갈 때 쓸지" 목록과 "그 주소에 나갈 수 있는지" 허용은 별개입니다. 양쪽 모두 그 주소를 포함해야 성공해요. 자체 서버에 올려 쓰는 구성에서는 아직 이 방식 자체를 지원하지 않는다는 점도 적혀 있습니다.

작업공간 전체가 참조할 수 있습니다

경고 상자로 따로 못 박은 대목입니다. 등록해둔 자격 묶음은 작업공간 범위라서, 그 작업공간에 접근할 수 있는 키를 가진 쪽이면 누구나 세션을 만들며 참조할 수 있습니다. 접근을 거두려면 그 묶음이나 항목을 없애는 수밖에 없어요.

정리하는 방법이 둘인데 성격이 다릅니다. 보관 처리는 비밀 값만 지우고 기록은 남겨 감사 흔적이 유지되고, 돌아가던 세션은 계속됩니다. 반면 완전 삭제는 기록까지 없앱니다. 값을 바꾸는 건 돌아가는 세션에도 재시작 없이 반영되고요. 다만 주소나 이름 같은 뼈대는 만든 뒤 못 바꿔서, 바꾸려면 보관 처리하고 새로 만들어야 합니다.

자주 묻는 질문 (FAQ)

Q. 등록할 때 키가 맞는지 확인해 주나요?

안 합니다. 준 값을 그대로 저장하고 실제로 세션이 돌 때가 되어서야 쓰입니다. 그래서 잘못된 값이면 등록 단계에서는 조용하고, 나중에 인증 오류로 튀어나옵니다. 게다가 그 오류가 세션을 멈추지도 않아요 — 신호만 나가고 작업은 계속됩니다. 연결 실패를 조용히 넘어가는 것과 같은 성격이라, 오류 신호를 받는 통로를 열어두는 게 중요합니다.

Q. 만료된 토큰은 알아서 갱신되나요?

위임 방식으로 등록하면서 갱신 정보를 같이 넣어뒀다면 됩니다. 만료되면 대신 새로 받아와요. 실패하면 별도 신호가 나가고, 원인을 확인하는 진단 기능도 따로 있습니다. 결과는 세 갈래인데 — 정상 / 권한이 사라져 다시 승인을 받아야 함 / 일시적 문제라 잠시 후 재시도입니다. 사용자에게 재승인을 요구할지 그냥 기다릴지 이걸로 갈라서 처리하면 됩니다.

Q. 같은 서비스 키를 두 개 넣으면요?

한 묶음 안에서는 거부됩니다. 대상 주소나 이름이 같은 항목이 이미 있으면 중복으로 막혀요. 바꾸려면 기존 것을 보관 처리해야 자리가 납니다. 다만 묶음을 여러 개 붙인 경우라면 이야기가 달라서, 같은 대상에 맞는 항목이 여럿이면 먼저 찾은 쪽이 이깁니다. 한 묶음에 담을 수 있는 개수에도 상한이 있습니다.

🧾 정직하게 밝혀둘 것

• 직접 등록해보지 않았습니다. 공식 문서의 동작·제약·경고를 정리한 것입니다.
• ★"키가 아니라 자리가 문제"라는 진단 각도는 제 해석입니다. 문서는 동작만 적었습니다.
• ★설정 이름·항목명·주소 표기·개수 상한은 전부 풀어서 적었습니다. 실제로 쓸 때는 원문을 확인하세요.
• 조직 계정에서 쓰는 제품군의 일부이고 시험 단계 표기로 제공됩니다.

✨ 정리하면

인증 실패가 뜨는데 키는 멀쩡하다면 자리를 의심하세요. 막힌 위치의 가짜 문자열은 바뀌지도 지워지지도 않고 그대로 나갑니다. 관리 화면에서 만들면 머리말만 켜지니 몸통에 실어 보내는 방식이면 따로 켜야 하고, 키로 토큰을 받아오거나 서명을 계산하는 방식은 아예 안 됩니다. 키 없이 가는 방법은 API 키 없이 인증하기, 조용히 넘어가는 연결 실패는 MCP 서버가 조용히 안 붙습니다, 환경 설계 전반은 하네스 엔지니어링, 전체 비용 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Claude 관리형 에이전트 자격증명 보관 공식 문서(2026년 8월 28일 열람). 조직 계정 전용이며 시험 단계 표기로 제공돼 동작과 제약이 바뀔 수 있습니다.