[Supabase][Auth] inviteUserByEmail 뒤 초대 링크가 원하는 URL로 안 갈 때 redirectTo와 email template를 같이 확인하는 법

IT 리서치 노트

[Supabase][Auth] inviteUserByEmail 뒤 초대 링크가 원하는 URL로 안 갈 때 redirectTo와 email template를 같이 확인하는 법

Supabase 초대 흐름을 붙이다 보면 inviteUserByEmail 호출은 성공했는데 사용자가 눌렀을 때 원하는 온보딩 화면이 아니라 기본 홈이나 엉뚱한 URL로 가는 경우가 생긴다. 2026년 7월 4일 기준 Supabase 공식 문서를 다시 보면 이 문제는 단순 메일 발송 성공 여부보다 redirectTo 값, Redirect URL allow list, 이메일 템플릿 변수 구성이 맞물리는 쪽에 가깝다. 이 글은 inviteUserByEmail 뒤 초대 링크가 원하는 URL로 안 갈 때 어디부터 다시 봐야 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 inviteUserByEmail 뒤 링크 도착지는 세 군데가 같이 맞아야 한다. 서버가 보낸 redirectTo, Supabase 콘솔의 Redirect URL allow list, 이메일 템플릿이 실제로 그 값을 품은 링크를 만드는지가 한 세트다. 셋 중 하나만 어긋나도 초대 메일은 정상 발송됐는데 사용자는 기본 Site URL이나 예상 밖 경로로 떨어질 수 있다.

이미 inviteUserByEmail와 createUser를 메일 발송 기준으로 나눈 글이 관리자 경로 선택을 다뤘다면, 이번 글은 초대 메일을 보낸 뒤 수락 경로를 어디서 검증할지에 더 가깝다. 또 service_role client와 세션 덮어쓰기 글을 같이 보면 왜 초대 수락 화면도 관리자 경로와 사용자 경로를 분리해 봐야 하는지 이해하기 쉽다.

실제 수락 라우트에서 token_hash를 어떻게 검증하고, 그 뒤 첫 비밀번호 설정 화면으로 어떤 순서로 넘길지까지 이어서 보고 싶다면 invite 수락 뒤 token_hash 검증과 첫 비밀번호 설정 화면을 붙이는 글이 바로 다음 단계다.

2. 어디서 실제로 막히는가

실무에서 자주 꼬이는 지점은 네 가지다. 첫째, 서버는 redirectTo를 보냈는데 콘솔 allow list에 같은 URL이 없다. 둘째, Redirect URL 설정은 맞는데 메일 템플릿이 기본 ConfirmationURL만 써서 redirect 값을 잃는다. 셋째, preview 환경 URL을 허용하지 않아 staging 초대만 실패한다. 넷째, 앱 수락 화면이 쿼리 파라미터를 읽지 못해 사용자가 비밀번호 설정으로 이어지지 못한다.

Supabase Redirect URLs 가이드는 redirectTo와 허용 URL 목록이 맞아야 한다고 설명하고, 이메일 템플릿 문서는 RedirectTo와 TokenHash, ConfirmationURL 변수를 따로 설명한다. inviteUserByEmail 문서를 함께 읽으면 초대 링크 검증은 메일 발송 성공 여부만으로 끝나지 않는다는 점이 분명해진다.

이때 많은 팀이 '메일이 왔으니 Supabase 쪽은 정상'이라고 결론 내리지만, 실제로는 클릭 뒤 이동 경로가 잘못된 경우가 더 자주 남는다. 메일 수신과 링크 도착지는 별도 단계로 나눠야 원인을 빨리 자를 수 있다.

• 증상: 초대 메일은 오는데 원하는 수락 화면이 안 열린다.
• 실패: redirectTo와 allow list를 같은 값으로 기록하지 않는다.
• 막힘: 템플릿이 RedirectTo를 쓰는지 확인하지 않는다.
• 누락: preview 또는 환경별 도메인을 허용 URL에 넣지 않는다.

상황	먼저 볼 곳	판단 기준
메일은 왔는데 홈으로 간다	Redirect URL allow list	보낸 redirectTo가 허용 URL과 정확히 맞는지 본다
메일 링크가 예전 경로를 쓴다	이메일 템플릿 변수	RedirectTo가 반영된 링크를 만드는지 본다
staging만 실패한다	wildcard 또는 환경별 URL	preview 도메인이 허용됐는지 본다

3. 실무에서 적용하는 순서

점검 순서는 다섯 단계가 가장 짧다. 먼저 서버 코드에서 inviteUserByEmail에 실제로 어떤 redirectTo를 넣었는지 기록한다. 두 번째로 Supabase 콘솔의 Redirect URLs 목록에 그 값이 그대로 들어 있는지 본다. 세 번째로 이메일 템플릿이 ConfirmationURL 또는 RedirectTo를 어떻게 쓰는지 확인한다. 네 번째로 수락 화면 라우트가 쿼리 파라미터를 처리하는지 검증한다. 마지막으로 메일을 실제로 클릭해 최종 도착 URL과 화면을 다시 확인한다.

1. 서버가 보낸 redirectTo 값을 로그에 남긴다.
2. Supabase Redirect URL allow list를 다시 본다.
3. 메일 템플릿이 RedirectTo를 반영하는지 확인한다.
4. 앱 수락 화면의 라우트와 쿼리 처리 로직을 점검한다.
5. 메일 클릭 뒤 최종 도착 URL을 실제로 재현한다.

핵심은 '초대 메일 수신'과 '초대 링크 도착지'를 다른 성공 조건으로 보는 것이다. 메일이 왔더라도 앱의 비밀번호 설정 화면이나 초대 수락 화면으로 가지 않으면 온보딩은 실패다. 이 해석은 Supabase 문서의 redirect 설정과 템플릿 변수를 함께 읽은 운영 기준이다.

검증 메모 예시

invite_api.redirectTo=https://example.com/auth/accept-invite
auth.redirect_urls includes https://example.com/auth/**
template.uses_redirect_to=true
template.uses_confirmation_url=true
final_clicked_url=https://example.com/auth/accept-invite?token_hash=...
accept_screen_loaded=true

이 정도만 남겨도 메일 단계와 링크 단계가 어디서 갈리는지 다음 장애 때 빠르게 재현할 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 inviteUserByEmail 호출 메모다. 초대 메일 API와 수락 경로를 같이 기록해 두면 redirectTo 검증이 어느 단계에서 필요한지 바로 보인다.

inviteUserByEmail 호출과 초대 수락 라우트를 함께 적어 둔 운영 메모 예시다.

즉 링크 목적지는 브라우저 signup 직후 세션처럼 자동으로 이어지는 값이 아니라, 초대 메일을 받은 사용자가 어디로 돌아올지를 정하는 값에 가깝다. 이미 inviteUserByEmail와 createUser를 메일 발송 기준으로 나눈 글을 읽었다면, 이번 글은 그 다음 단계인 링크 도착지 검증이다.

두 번째 자료는 Redirect URLs 가이드의 개요다. Supabase는 redirectTo가 인증 뒤 사용자를 어디로 보낼지 정하고, 그 URL이 allow list와 맞아야 한다고 설명한다.

Supabase Redirect URLs 문서는 redirectTo와 허용 URL 목록이 함께 맞아야 한다고 설명한다.

여기서 막히면 메일은 정상 발송됐는데 클릭 뒤 Site URL이나 기본 경로로 떨어질 수 있다. 많은 팀이 초대 메일 템플릿만 보고 문제를 찾지만, 실제로는 allow list와 redirectTo가 먼저 어긋난 경우가 적지 않다.

세 번째 자료는 redirectTo를 쓸 때 이메일 템플릿을 같이 봐야 한다는 구간이다. 초대 링크가 예상과 다른 경로로 가는 문제는 템플릿이 기본 ConfirmationURL을 그대로 쓰는지, RedirectTo 변수를 반영하는지에 따라 갈린다.

redirectTo를 쓸 때 이메일 템플릿 구성도 같이 확인해야 한다는 Supabase 가이드 구간이다.

즉 콘솔의 URL 설정만 맞춰도 끝나지 않는다. 템플릿이 실제로 redirectTo 값을 품은 링크를 만들고 있는지까지 봐야 한다.

네 번째 자료는 이메일 템플릿 변수 설명이다. 여기서는 RedirectTo와 TokenHash, ConfirmationURL이 어떤 역할인지 확인할 수 있다.

Supabase 이메일 템플릿 문서는 RedirectTo와 TokenHash 같은 핵심 변수를 따로 설명한다.

초대 메일을 커스텀할 때 이 변수 구성이 흐트러지면 링크가 아예 기본 Site URL로 가거나, 서버 쪽 수락 엔드포인트를 거치지 못할 수 있다. 이 부분은 invite 경로를 자체 온보딩 화면과 연결하는 팀에게 특히 중요하다.

실무에서는 초대 호출 코드와 수락 화면 경로를 한 번에 메모해 두는 편이 좋다. 서버에서 어떤 redirectTo를 넣었는지, 템플릿에 어떤 플레이스홀더를 썼는지가 함께 남아야 재현이 쉽다.

inviteUserByEmail 호출과 초대 수락 URL을 같이 남기는 예시다.

이렇게 기록해 두면 메일 발송은 됐는데 링크가 기본 홈으로 가는 문제를 빠르게 다시 볼 수 있다. 또 createUser와 signUp을 세션 반환 기준으로 나눈 글과 연결하면 초대 경로를 공개 가입과 헷갈릴 가능성도 줄어든다.

마지막 자료는 초대 링크 도착지 점검표다. 문제가 나면 어느 화면부터 다시 볼지 순서를 고정해 두는 편이 낫다.

inviteUserByEmail 뒤 링크 도착지 문제가 날 때 다시 볼 값들을 정리한 체크리스트다.

이 표가 있으면 allow list, 템플릿, 앱 라우트, 메일 클릭 뒤 실제 URL을 따로 추적하지 않아도 된다. 특히 preview URL이나 환경별 도메인이 섞이는 팀에서는 이 순서가 재발 방지에 도움이 된다.

5. 주의사항과 리스크

첫 번째 리스크는 템플릿을 과하게 커스텀해 RedirectTo 흐름을 깨뜨리는 것이다. 두 번째 리스크는 preview URL을 넓게 열어 두고 프로덕션과 같은 기준으로 관리하지 않는 것이다. 세 번째 리스크는 메일이 왔다는 이유만으로 수락 화면까지 검증하지 않는 것이다.

운영 전에 최소한 프로덕션, staging, preview 중 실제로 쓰는 환경별 초대 링크를 한 번씩 눌러 보고 최종 도착 URL과 화면을 캡처해 두는 편이 좋다. 필요하면 서버 쪽 수락 엔드포인트를 둬 token hash와 초대 상태를 먼저 기록하는 방법도 고려할 수 있다.

• redirectTo, allow list, 템플릿 링크가 따로 놀면 초대는 성공해도 온보딩은 실패한다.
• 환경별 도메인이 있다면 허용 URL 목록을 운영 문서로 같이 관리한다.
• 메일 클릭 뒤 최종 수락 화면까지 실제로 본 뒤 완료 처리한다.

6. 결론

Supabase inviteUserByEmail 뒤 링크 도착지 문제는 메일 API 하나만 보면 잘 안 풀린다. 서버의 redirectTo, Supabase 콘솔의 Redirect URLs, 이메일 템플릿의 변수 구성이 함께 맞아야 원하는 초대 수락 화면으로 도착한다.

• 메일 수신과 링크 도착지는 별도 성공 조건으로 본다.
• Redirect URL allow list와 템플릿 변수를 함께 확인한다.
• 환경별 수락 화면 도착 URL을 실제 클릭으로 검증한다.

7. 참고 링크

1. https://supabase.com/docs/reference/javascript/auth-admin-inviteuserbyemail
2. https://supabase.com/docs/guides/auth/redirect-urls
3. https://supabase.com/docs/guides/auth/auth-email-templates
4. https://supabase.com/docs/reference/javascript/auth-resetpasswordforemail