스코프 레퍼런스
요청 가능한 scope 목록과 각 scope가 제공하는 사용자 정보를 정리한 레퍼런스입니다.
인증 요청의 scope 파라미터에 공백으로 구분해 넣습니다. 요청한 스코프는 동의 화면에서 사용자에게 그대로 보여집니다.
요청할 수 있는 스코프
| 스코프 | 동의 화면 표기 | 부여 방식 |
|---|---|---|
profile.basic | UUID, 닉네임, 이메일 | 모든 서비스 기본 |
profile.avatar | 프로필 사진 URL | 모든 서비스 기본 |
service.domain.read | 연결된 서비스의 도메인 상세정보 | 관리자 수동 부여 |
service.member_email.read | 회원 이메일 주소 | 내부 마커 — 직접 요청하지 않습니다(아래 참고) |
스코프를 하나도 넣지 않거나 목록에 없는 값을 넣으면 invalid_scope로 거부됩니다.
서비스에 부여되지 않은 스코프를 요청하면 insufficient_scope입니다.
★ 이메일 정책 — 기본 제공(opt-out)
이메일은 profile.basic에 통합되어 기본으로 제공됩니다.
따로 요청하는 스코프가 아니라, profile.basic에 동의받으면 자동으로 따라옵니다.
서비스가 이메일을 받지 않도록 끄는 것(opt-out)은 가능합니다. 이 경우
service.member_email.read 마커가 유효 스코프에 붙지 않고,
/oauth/userinfo 응답에서 email 필드가 빠집니다.
정리하면 email 필드가 오는 조건은 두 가지가 모두 참일 때입니다.
- 토큰의 유효 스코프에
profile.basic이 있을 것 - 해당 서비스에서 이메일 제공이 꺼져 있지 않을 것
이메일이 안 온다면 스코프 문제가 아니라 서비스의 이메일 제공 설정이 꺼져 있는 것일 수 있습니다. 관리자에게 확인하세요.
스코프별로 늘어나는 응답 필드
| 필드 | 언제 오나 | 설명 |
|---|---|---|
sub | 항상 | 서비스별로 다른 사용자 식별자(pairwise) |
nickname | 항상 | 사용자 닉네임 |
scope | 항상 | 이 토큰의 유효 스코프 |
profile_image_url | profile.avatar | 프로필 사진 URL. 사진이 없으면 null |
email | 위 두 조건 충족 | 이메일 주소 |
service.domain.read
사용자가 놀아 계정에 등록해 둔 자기 서비스 목록을 읽는 스코프입니다.
일반 로그인에는 필요 없고, 서비스 관리 도구를 만드는 경우에만 씁니다.
관리자가 수동으로 부여하며, 부여 없이 요청하면 insufficient_scope가 납니다.
읽는 방법은 API 레퍼런스의 /oauth/domain-info를 보세요.
권장 조합
scope=profile.basic profile.avatar // 일반적인 소셜 로그인 scope=profile.basic // 사진이 필요 없을 때
필요 없는 스코프를 요청하면 동의 화면이 길어지고 이탈이 늘어납니다. 실제로 쓰는 것만 요청하세요.