Bearer 토큰과 API 키의 차이는 무엇인가요?

Bearer 토큰과 API 키는 양자택일이 아닙니다. Bearer는 Authorization: Bearer <token> 헤더에 자격 증명을 담아 보내는 방식이고, API 키는 자격 증명의 한 종류로 직접 만들고 폐기하는 시크릿입니다. 그래서 API 키를 bearer 토큰으로 보낼 수 있습니다. OAuth 액세스 토큰도 bearer 토큰으로 보내는 자격 증명이지만 API 키와는 다른 것으로, 정해진 스코프와 기간에 한해 앱에 발급됩니다.

정의는 RFC 6750, RFC 6749, RFC 9110에서 인용했고, Sume 관련 내용은 인증과 MCP OAuth와 API 키 문서에서 가져왔습니다. 모두 2026-09-28에 확인했습니다.

Bearer 토큰이란 무엇인가요?

OAuth 2.0 bearer 토큰 표준인 RFC 6750은 이 토큰을 한 가지 속성으로 정의합니다. 토큰을 소유한 당사자, 즉 소지자(bearer)는 누구든 다른 소지자와 똑같은 방식으로 토큰을 쓸 수 있으며, 암호 키를 보유했음을 증명할 필요가 없습니다. 이 이름은 토큰이 무엇인지가 아니라 어떻게 쓰이는지를 나타냅니다. 표준의 예시는 Bearer 스킴으로 Authorization 헤더에 토큰을 담아 보냅니다.

토큰을 가진 사람이면 누구나 쓸 수 있으므로, RFC 6750은 클라이언트가 토큰을 보낼 때 항상 TLS(https)를 써야 한다고 말합니다.

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM

API 키와 액세스 토큰은 같은 것인가요?

아니요, 둘 다 bearer 토큰으로 보낼 수는 있지만 다른 것입니다. RFC 6749는 OAuth 액세스 토큰을 클라이언트에 발급된 인가를 나타내는 문자열로 설명하며, 이 인가는 최종 사용자 같은 리소스 소유자가 허락한 특정 스코프와 접근 기간에 한정됩니다. RFC 6750은 토큰 서버가 수명이 짧은, 즉 한 시간 이하인 bearer 토큰을 발급하도록 권장합니다. 반면 Sume API 키는 API Keys 대시보드에서 워크스페이스 하나를 대상으로 직접 만드는 키로, 스코프는 만들 때 고정되고, 현재 코드에서는 폐기할 때까지 동작합니다.

Sume의 호스팅 MCP 서버는 둘 다 받지만, 문서에 따르면 두 자격 증명은 서로 바꿔 쓸 수 없습니다. MCP OAuth 토큰은 Sume API 키가 아닙니다.

API 키는 Bearer로 보내야 하나요, x-api-key로 보내야 하나요?

해당 API 문서에 나온 방식을 따르세요. Authorization은 클라이언트가 서버에 자신을 인증할 때 쓰는 표준 HTTP 헤더이고, x-api-key는 API가 자체적으로 정한 헤더 이름입니다. RFC 6750에는 어떤 자격 증명에든 따라 할 만한 규칙도 있습니다. 한 요청 안에서 토큰을 두 가지 이상의 방법으로 보내지 말라는 것입니다.

Sume는 키를 두 방식 모두로 받으며 이 규칙을 강제합니다. 두 헤더를 모두 실은 요청은 401 unauthorized와 Send only one API key credential. 메시지로 거부됩니다. 스코프와 호스트는 Sume API 키 동작 방식에서 다룹니다.

API 키를 URL에 넣어 보내도 되나요?

넣지 마세요. RFC 6750은 브라우저, 웹 서버 등의 소프트웨어가 브라우저 기록과 서버 로그에 남은 URL을 충분히 보호하지 못할 수 있으므로, bearer 토큰을 쿼리 문자열 파라미터 같은 형태로 페이지 URL에 담아 보내면 안 된다고 말합니다. access_token 쿼리 파라미터를 문서화하긴 하지만, 헤더와 본문을 모두 쓸 수 없는 경우가 아니면 쓰지 말라고 하며 그 사용을 권장하지 않는다고 밝힙니다.

Sume에는 쿼리 파라미터 옵션이 없습니다. 현재 코드에서 API는 x-api-key와 Authorization 헤더에서만 키를 읽으며, 둘 다 없는 요청에는 Missing API key. Send x-api-key or Authorization: Bearer.라고 응답합니다. 키가 로그나 채팅 기록에 남았다면 문서는 키를 교체하라고 안내합니다. 교체 과정은 API 키가 노출됐다면?에서 차례로 설명합니다.