AI 에이전트가 어떤 서비스 API를 호출하다가 401을 받았다고 해보겠습니다. 사람이라면 회원가입 페이지를 열고, 이메일을 인증하고, 필요한 권한을 승인한 뒤, API 키나 토큰을 발급받을 수 있습니다. 하지만 에이전트에게는 이 과정이 서비스마다 제각각이고, 어디서 시작해야 하는지도 명확하지 않습니다.
WorkOS가 공개한 auth.md는 이 문제를 다룹니다. 핵심은 간단합니다. 서비스가 에이전트에게 “우리 서비스에 등록하려면 이렇게 하라”는 절차를 표준화된 방식으로 알려주는 것입니다.
auth.md는 에이전트용 등록 안내서다
auth.md는 애플리케이션이 https://yourservice.com/auth.md에 공개하는 일반 Markdown 문서입니다.1 이 파일에는 에이전트가 사용할 수 있는 등록 흐름, 요청 가능한 scope, 사용자 연결 자격 증명을 얻는 방법이 담깁니다.
다만 단순한 설명 문서로만 보면 부족합니다. WorkOS는 auth.md를 OAuth 표준을 기반으로 한 공개 에이전트 등록 프로토콜로 설명합니다. 문서는 사람이 읽을 수 있는 Markdown이지만, 에이전트가 실제로 실행할 수 있도록 요청 형식과 엔드포인트 정보도 함께 제공합니다.
예를 들어 auth.md 프로토콜은 다음과 같은 엔드포인트 집합을 포함합니다.1
/agent-auth/agent-auth/claim/agent-auth/claim/complete
즉 auth.md는 “문서”이면서 동시에 “등록 절차의 진입점”입니다.
왜 필요한가: 에이전트가 추측하지 않게 하기 위해
기존 OAuth 흐름은 사람과 애플리케이션 사이의 권한 위임을 잘 다룹니다. 하지만 AI 에이전트가 처음 보는 서비스에 접근할 때는 여전히 빈틈이 있습니다. 에이전트는 어떤 등록 방식이 지원되는지, 어떤 scope를 요청해야 하는지, 사용자 확인이 필요한지 등을 스스로 추측해야 할 수 있습니다.
auth.md의 역할은 이 추측을 줄이는 것입니다. WorkOS는 auth.md가 /.well-known/oauth-protected-resource의 Protected Resource Metadata를 확장하고, RFC 9728의 Protected Resource Metadata를 검색 계층으로 활용한다고 설명합니다.1
흐름을 단순화하면 다음과 같습니다.
에이전트가 API에 접근하다가 인증이 필요하다는 신호를 받습니다.
Protected Resource Metadata와 Authorization Server metadata를 확인합니다.
agent_auth정보를 통해 지원되는 등록 방식을 파악합니다.auth.md를 읽고 적절한 등록 절차를 따릅니다.
이 구조에서 auth.md는 OAuth를 대체하는 것이 아니라, 에이전트가 OAuth 기반 등록 흐름을 발견하고 이해하도록 돕는 안내 계층에 가깝습니다.
auth.md 문서에는 무엇이 들어가나
auth.md는 일반 Markdown이므로 사람이 읽기 쉽습니다. 동시에 에이전트가 필요한 값을 추출할 수 있도록 구조화될 수 있습니다. WorkOS는 auth.md 문서가 탐색용 제목, 요청 형식 추출용 fenced code block, 보충 설명용 본문을 포함할 수 있다고 설명합니다.1
문서에는 예를 들어 다음과 같은 섹션이 들어갈 수 있습니다.1
Discover
Pick a method
Register
Claim ceremony
Use the credential
Errors
Revocation
여기서 중요한 부분은 Discover, Pick a method, Register입니다. Discover 단계는 Protected Resource Metadata와 Authorization Server metadata를 가져오는 방법을 설명합니다. Pick a method 단계는 어떤 등록 방식을 선택할지 판단 기준을 제공합니다. Register 단계는 선택한 방식에 따른 요청과 응답 형식을 안내합니다.
따라서 auth.md를 작성한다는 것은 단순히 “API 사용법”을 적는 것이 아닙니다. 에이전트가 등록을 시작해 자격 증명을 얻고, 실패하거나 철회될 때까지의 경로를 명확히 공개하는 일입니다.
등록 방식의 핵심 선택지
auth.md에서 특히 중요한 판단은 에이전트를 어떻게 신뢰할 것인가입니다. WorkOS가 설명하는 선택지는 크게 두 갈래입니다.
첫 번째는 identity_assertion 방식입니다. 신뢰할 수 있는 에이전트 제공자가 “이 에이전트는 특정 사용자를 대신한다”고 주장하고, 서비스가 그 주장을 검증한 뒤 자격 증명을 발급하는 흐름입니다.1 이 방식은 에이전트 제공자와 서비스 사이에 신뢰 관계를 설정할 수 있을 때 적합합니다.
두 번째는 익명 등록 또는 claim 흐름입니다. 에이전트 제공자를 바로 신뢰하기 어렵거나 사용자 식별 정보가 충분하지 않을 때 사용할 수 있습니다. 이 경우 에이전트는 먼저 등록하고, 이후 사용자가 이메일 OTP 같은 절차를 통해 해당 등록을 자신의 것으로 연결합니다.1
서비스 입장에서는 이 선택이 중요합니다. 모든 에이전트를 같은 방식으로 받을 필요는 없습니다. 신뢰할 수 있는 제공자에게는 identity assertion을 허용하고, 그렇지 않은 경우에는 사용자 확인이 포함된 claim 흐름을 요구할 수 있습니다. auth.md는 이런 정책을 에이전트가 미리 알 수 있게 만드는 공개 인터페이스입니다.
도입 전에 봐야 할 현실적인 지점
auth.md의 가치는 명확합니다. 에이전트가 서비스마다 다른 가입 절차를 추측하지 않고, 공개된 절차를 따라 제한된 권한을 얻을 수 있게 합니다. 에이전트 친화적인 API를 설계하려는 팀이라면 이 방향을 주목할 만합니다.
다만 아직 생태계 표준으로 굳어진 단계는 아닙니다. GitHub 이슈에서는 SSO, 멀티 리전, 기존 OAuth Dynamic Client Registration 등과의 관계를 더 명확히 해야 한다는 논의도 있습니다.2 따라서 당장 모든 인증 체계를 auth.md 중심으로 재설계하기보다는, 에이전트 접근을 열 계획이 있는 서비스가 실험적으로 검토할 초기 프로토콜로 보는 편이 현실적입니다.
실무적으로는 다음 질문부터 점검할 수 있습니다.
우리 API는 에이전트가 인증 실패 후 다음 단계를 발견할 수 있는가?
에이전트에게 허용할 scope와 제한 조건이 명확한가?
신뢰할 수 있는 에이전트 제공자와 그렇지 않은 경우를 구분할 수 있는가?
사용자가 나중에 에이전트 등록을 확인하거나 철회할 수 있는가?
auth.md가 던지는 질문은 결국 하나입니다. 사람이 아닌 에이전트가 처음 방문했을 때, 우리 서비스는 안전하게 등록하고 제한된 권한을 받을 수 있는 길을 제공하는가?
에이전트가 API의 주요 사용자가 될수록, 이 질문은 인증 설계의 출발점이 될 가능성이 큽니다.
1Agent Registration with Auth.md -- WorkOS
2SSO support, multiregion support, comparison to related RFCs · Issue #1 · workos/auth.md
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.