Gnuboard7/docs/backend/api/users.md

Users API 레퍼런스

소유: 코어 · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.

---

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Users 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

---

GET /api/admin/users

• 라우트명: api.admin.users.index
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@index
• 인증/권한: auth:sanctum + permission:core.users.read

요청 파라미터

이름	위치	타입	필수	허용값	용도
page	query	integer	아니오	min 1	조회할 페이지 번호 (1부터 시작)
per_page	query	integer	아니오	min 1, max 100	페이지당 항목 수
filters	query	array	아니오	max 10	추가 필터 조건 맵 (필드별 조건)
start_date	query	date	아니오	—	조회 기간 시작일 (이 날짜 이후 데이터)
end_date	query	date	아니오	—	조회 기간 종료일 (이 날짜 이전 데이터)
date_filter	query	string	아니오	all, week, month, custom	가입 기간 프리셋 (all: 전체, week: 최근 1주, month: 최근 1개월, custom: start_date/end_date 로 직접 지정)
sort_by	query	string	아니오	created_at, name, email, last_login_at	정렬 기준 필드명
sort_order	query	string	아니오	asc, desc	정렬 방향 (asc 오름차순 / desc 내림차순)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.list_validation_rules).

응답 필드 (data 내부)

목록 응답: data.data[] 배열 항목의 필드 + data.pagination.

필드	타입	실측 예시값	용도/설명
number	integer	156	목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생)
uuid	string	a231747f-e82e-4cf2-9ae1-a261849dce40	외부 노출용 UUID (URL/API 식별자, 내부 id 비노출)
name	string	API 문서 샘플 사용자	사용자 이름
nickname	string	gunwoo.oh	닉네임
email	string	apidoc-sample-user@example.com	이메일 주소
language	string	ko	사용자 언어 설정 (ko: 한국어, en: 영어)
language_label	string	한국어	언어 코드의 현지화 라벨 (user.language.{code} 번역)
country	string	KR	국가 코드 (ISO 3166-1 alpha-2)
country_flag	string	🇰🇷	국가 코드의 국기 이모지 (country 값에서 파생)
country_name	string	한국	국가 코드의 현지화 국가명 (country 값에서 파생)
status	string	active	계정 상태 (active: 활성, inactive: 비활성, blocked: 차단, withdrawn: 탈퇴)
status_label	string	활성	상태의 사람이 읽는 라벨 (상태 Enum label() 산물)
status_variant	string	success	상태 표시 색상/스타일 변형 키 (상태 Enum variant() 산물 — UI 배지용)
mobile	string	010-9070-5662	휴대폰 번호
roles	array	[{"id":1,"identifier":"admin","name":"관리자"}]	사용자에게 부여된 역할 목록 (원소: id/identifier/name — 역할 관계 파생)
email_verified_at	string	2026-07-06 19:15:16	email verified 일시
last_login_at	string	2026-07-05 19:15:16	last login 일시
created_at	string	2026-07-06	생성 일시
is_owner	boolean	true	현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타)
abilities	object	{"can_read":true,"can_create":true,"can_update":true,"can…	현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.read)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

관리자 사용자 관리 화면(admin_user_list.json)의 목록을 제공합니다. filters 로 이름/이메일 다중 검색(operator: like, eq, starts_with, ends_with), date_filter(all/week/month/custom)와 start_date/end_date 로 가입 기간 필터, sort_by/sort_order 로 정렬한다. 응답은 data.data[](항목별 순번 number + 요약 필드)와 data.pagination(페이지 정보)에 더해 data.statistics(통계)와 data.abilities(컬렉션 레벨 권한)를 함께 반환한다. 기본값은 per_page=15, page=1, sort_by=created_at, sort_order=desc, date_filter=all 이다.

POST /api/admin/users

• 라우트명: api.admin.users.store
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@store
• 인증/권한: auth:sanctum + permission:core.users.create

요청 파라미터

이름	위치	타입	필수	허용값	용도
name	body	string	예	max 255	대상의 이름/명칭
nickname	body	string	아니오	max 50	닉네임
email	body	email	예	max 255	이메일 주소
password	body	string	예	—	비밀번호
language	body	string	아니오	ko, en, fr, ja	언어 코드
country	body	string	아니오	—	국가 코드 (ISO 3166-1 alpha-2)
timezone	body	string	아니오	—	타임존 식별자
status	body	string	아니오	active, inactive, blocked, withdrawn	계정 상태 (미지정 시 active)
homepage	body	string	아니오	max 255	홈페이지 URL
mobile	body	string	아니오	max 20	휴대전화 번호
phone	body	string	아니오	max 20	전화번호
zipcode	body	string	아니오	max 10	우편번호
address	body	string	아니오	max 255	기본 주소
address_detail	body	string	아니오	max 255	상세 주소
signature	body	string	아니오	max 1000	서명
bio	body	string	아니오	max 5000	자기소개
admin_memo	body	string	아니오	max 5000	관리자 전용 메모 (해당 사용자에 대한 내부 기록, 사용자에게 노출 안 됨)
roles	body	array	아니오	min 1	부여할 역할 객체 배열 [{id}] (role_ids 와 병용 시 role_ids 우선)
role_ids	body	array	아니오	min 1	role 식별자 배열
notify_post_complete	body	boolean	아니오	—	게시글 작성 완료 알림 수신 여부 (게시판 모듈 알림 설정)
notify_post_reply	body	boolean	아니오	—	내 게시글에 답글이 달릴 때 알림 수신 여부
notify_comment	body	boolean	아니오	—	내 게시글에 댓글이 달릴 때 알림 수신 여부
notify_reply_comment	body	boolean	아니오	—	내 댓글에 대댓글이 달릴 때 알림 수신 여부
email_subscription	body	boolean	아니오	—	광고성 이메일 수신 동의 여부 (marketing 플러그인 채널 동의, marketing_consents 테이블에 저장)
marketing_consent	body	boolean	아니오	—	마케팅 정보 수신 전체 동의 마스터 키 (marketing 플러그인이 검증 규칙 주입, 상세는 user-consent-injection.md)
third_party_consent	body	boolean	아니오	—	제3자 정보 제공 동의 여부 (marketing 플러그인 법적 동의 항목)
info_disclosure	body	boolean	아니오	—	개인정보 이용 안내 동의 여부 (marketing 플러그인 법적 동의 항목)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.create_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.create)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

관리자가 새 사용자를 생성합니다. name, email, password(8자 이상, password_confirmation 확인 필수), 그리고 역할이 필수이다 — 역할은 roles(객체 배열 [{id}]) 또는 role_ids(id 배열) 중 하나로 지정하며 둘 다 보내면 role_ids 가 우선한다. language(미지정 시 ko), status(미지정 시 active), 연락처/주소/자기소개 등은 선택 항목이다. 성공 시 201 과 함께 생성된 사용자를 UserResource 형태로 반환한다. notify_*/marketing_consent/third_party_consent/info_disclosure/email_subscription 파라미터는 확장(sirsoft-marketing)이 검증 규칙을 주입한 필드로, 상세는 해당 확장 문서를 참조한다.

PATCH /api/admin/users/bulk-status

• 라우트명: api.admin.users.bulk-status
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@bulkUpdateStatus
• 인증/권한: auth:sanctum + permission:core.users.update

요청 파라미터

이름	위치	타입	필수	허용값	용도
ids	body	array	예	min 1	대상 리소스 식별자 배열 (대량 작업 대상)
status	body	string	예	—	일괄 적용할 계정 상태 (UserStatus Enum 값: active/inactive/blocked/withdrawn/pending_verification)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.bulk_update_status_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.update)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

여러 사용자의 계정 상태를 한 번에 변경합니다. ids 는 대상 사용자 UUID 배열이며, status 는 active/inactive/blocked/withdrawn/pending_verification(UserStatus Enum 값) 중 하나이다. ExcludeCurrentUser 규칙으로 요청자 본인은 대상에서 제외된다. 목록 화면의 다중 선택 후 일괄 상태 변경에 사용한다.

POST /api/admin/users/check-email

• 라우트명: api.admin.users.check-email
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@checkEmail
• 인증/권한: auth:sanctum + permission:core.users.read

요청 파라미터

이름	위치	타입	필수	허용값	용도
email	body	email	예	max 255	이메일 주소
exclude_user_id	body	uuid	아니오	—	exclude user 식별자

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.check_email_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.read)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

이메일 주소의 사용 가능 여부(중복 아님)를 확인합니다. email 은 필수, exclude_user_id(UUID)를 주면 해당 사용자를 중복 검사에서 제외한다 — 사용자 수정 화면에서 자기 자신의 이메일을 유지할 때 사용한다. 응답 data.available 이 true 면 사용 가능, false 면 이미 사용 중이다. 사용자 생성/수정 폼의 이메일 실시간 중복 확인에 쓰인다.

PATCH /api/admin/users/me/language

• 라우트명: api.admin.users.me.language
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@updateMyLanguage
• 인증/권한: auth:sanctum

요청 파라미터

이름	위치	타입	필수	허용값	용도
language	body	string	예	ko, en, fr, ja	언어 코드

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.update_language_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

현재 로그인한 사용자 본인의 언어 설정을 변경합니다. 별도 권한 없이 auth:sanctum 인증만 요구하며(다른 사용자를 대상으로 하지 않음), language 는 config('app.supported_locales')(예: ko, en, fr, ja) 중 하나여야 한다. 성공 시 갱신된 사용자를 UserResource 로 반환하며, 관리자 UI 의 언어 전환에 사용한다.

GET /api/admin/users/recent

• 라우트명: api.admin.users.recent
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@recent
• 인증/권한: auth:sanctum + permission:core.users.read

요청 파라미터

요청 파라미터 없음.

응답 필드 (data 내부)

필드	타입	실측 예시값	용도/설명
uuid	string	a231747f-e82e-4cf2-9ae1-a261849dce40	외부 노출용 UUID (URL/API 식별자, 내부 id 비노출)
name	string	API 문서 샘플 사용자	사용자 이름
nickname	string	gunwoo.oh	닉네임
email	string	apidoc-sample-user@example.com	이메일 주소
avatar	null	null	프로필 아바타 이미지 URL (미설정 시 null)
language	string	ko	사용자 언어 설정 (ko: 한국어, en: 영어)
language_label	string	한국어	언어 코드의 현지화 라벨 (user.language.{code} 번역)
country	string	KR	국가 코드 (ISO 3166-1 alpha-2)
status	string	active	계정 상태 (active: 활성, inactive: 비활성, blocked: 차단, withdrawn: 탈퇴)
status_label	string	활성	상태의 사람이 읽는 라벨 (상태 Enum label() 산물)
status_variant	string	success	상태 표시 색상/스타일 변형 키 (상태 Enum variant() 산물 — UI 배지용)
is_admin	boolean	true	관리자 역할 보유 여부 (User::isAdmin() — 역할 관계 기반 파생)
homepage	string	https://example.com	홈페이지 URL
mobile	string	010-9070-5662	휴대폰 번호
phone	string	02-805-4759	전화번호
zipcode	string	93153	우편번호
address	string	대구광역시 북구 백제고분로 720	기본 주소
address_detail	string	40동 835호	상세 주소
signature	string	Ipsam rem amet expedita est.	서명
bio	string	Tenetur omnis et amet omnis veniam to…	자기소개
last_login_at	string	2026-07-05 19:15:16	last login 일시
email_verified_at	string	2026-07-06 19:15:16	email verified 일시
timezone	string	Asia/Seoul	사용자 시간대 (예: Asia/Seoul, UTC)
created_at	string	2026-07-06 19:15:16	생성 일시
updated_at	string	2026-07-06 19:15:16	최종 수정 일시
is_owner	boolean	true	현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타)
abilities	object	{"can_read":true,"can_create":true,"can_update":true,"can…	현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.read)이 없는 경우

설명

최근 가입한 사용자 10명을 최신순으로 반환합니다. 파라미터는 없으며, UserResource 전체 필드(관계형 데이터는 미로드)를 담은 컬렉션을 반환한다. 관리자 대시보드의 최근 가입자 위젯이 소비한다.

GET /api/admin/users/search

• 라우트명: api.admin.users.search
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@search
• 인증/권한: auth:sanctum + permission:core.users.read

요청 파라미터

이름	위치	타입	필수	허용값	용도
keyword	query	string	아니오	max 255	검색 키워드 (부분 일치)
uuid	query	uuid	아니오	—	특정 사용자 UUID 로 단건 조회 (지정 시 keyword 무시하고 해당 UUID 사용자만 반환)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.search_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.read)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

사용자를 검색해 UserResource 컬렉션으로 반환합니다. uuid 를 주면 해당 UUID 의 단일 사용자(존재 시 1건, 없으면 빈 배열)를, 없으면 keyword 로 이름·닉네임·이메일을 부분 일치 검색한다(keyword 와 uuid 중 하나는 필수). 알림 템플릿 수신자 지정이나 활동 로그 필터의 사용자 선택 UI 에서 사용한다.

GET /api/admin/users/statistics

• 라우트명: api.admin.users.statistics
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@statistics
• 인증/권한: auth:sanctum + permission:core.users.read

요청 파라미터

요청 파라미터 없음.

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드	타입	실측 예시값	용도/설명
total_users	integer	156	전체 사용자 수 (통계 객체는 count/추이 포함)
users_this_week	integer	1	이번 주 신규 가입자 수
users_this_month	integer	155	이번 달 신규 가입자 수
users_today	integer	0	오늘 신규 가입자 수
active_users_this_week	integer	2	이번 주 활동(로그인) 사용자 수
language_distribution	object	{"ko":92,"en":64}	언어별 사용자 분포 (언어 코드 => 사용자 수)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.read)이 없는 경우

설명 관리자 대시보드의 사용자 통계 위젯이 소비하는 집계 API. 캐시 없이 실시간 집계.

DELETE /api/admin/users/{user}

• 라우트명: api.admin.users.destroy
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@destroy
• 인증/권한: auth:sanctum + permission:core.users.delete

요청 파라미터

이름	위치	타입	필수	허용값	용도
user	path	string	예	—	대상 user의 식별자

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.delete_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.delete)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

지정한 사용자(경로 파라미터는 UUID 로 바인딩)를 삭제합니다. 슈퍼관리자 계정은 삭제할 수 없으며 시도 시 422(exceptions.cannot_delete_super_admin)를 반환한다. 그 외 삭제 실패 시에는 실패 상세 사유가 담긴 422 를, 나머지 오류는 500 을 반환한다. 삭제는 Service 계층에서 관련 데이터 정리와 훅을 거쳐 처리된다.

GET /api/admin/users/{user}

• 라우트명: api.admin.users.show
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@show
• 인증/권한: auth:sanctum + permission:core.users.read

요청 파라미터

이름	위치	타입	필수	허용값	용도
user	path	string	예	—	대상 user의 식별자

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드	타입	실측 예시값	용도/설명
uuid	string	a231747f-e82e-4cf2-9ae1-a261849dce40	외부 노출용 UUID (URL/API 식별자, 내부 id 비노출)
name	string	API 문서 샘플 사용자	사용자 이름
nickname	string	gunwoo.oh	닉네임
email	string	apidoc-sample-user@example.com	이메일 주소
avatar	null	null	프로필 아바타 이미지 URL (미설정 시 null)
language	string	ko	사용자 언어 설정 (ko: 한국어, en: 영어)
language_label	string	한국어	언어 코드의 현지화 라벨 (user.language.{code} 번역)
country	string	KR	국가 코드 (ISO 3166-1 alpha-2)
status	string	active	계정 상태 (active: 활성, inactive: 비활성, blocked: 차단, withdrawn: 탈퇴)
status_label	string	활성	상태의 사람이 읽는 라벨 (상태 Enum label() 산물)
status_variant	string	success	상태 표시 색상/스타일 변형 키 (상태 Enum variant() 산물 — UI 배지용)
is_admin	boolean	true	관리자 역할 보유 여부 (User::isAdmin() — 역할 관계 기반 파생)
homepage	string	https://example.com	홈페이지 URL
mobile	string	010-9070-5662	휴대폰 번호
phone	string	02-805-4759	전화번호
zipcode	string	93153	우편번호
address	string	대구광역시 북구 백제고분로 720	기본 주소
address_detail	string	40동 835호	상세 주소
signature	string	Ipsam rem amet expedita est.	서명
bio	string	Tenetur omnis et amet omnis veniam to…	자기소개
last_login_at	string	2026-07-05 19:15:16	last login 일시
email_verified_at	string	2026-07-06 19:15:16	email verified 일시
timezone	string	Asia/Seoul	사용자 시간대 (예: Asia/Seoul, UTC)
modules_count	integer	0	modules 개수 (집계)
plugins_count	integer	0	plugins 개수 (집계)
menus_count	integer	2	menus 개수 (집계)
modules	array	[]	이 사용자가 접근 권한을 가진 모듈 목록 (역할 경유 권한 관계 파생)
plugins	array	[]	이 사용자가 접근 권한을 가진 플러그인 목록 (역할 경유 권한 관계 파생)
menus	array	[{"id":33,"title":"API 문서 샘플 메뉴","url":"\/admin\/apidoc-s…	이 사용자가 접근 가능한 관리자 메뉴 목록 (원소: id/title/url — 역할 경유 메뉴 관계 파생)
roles	array	[{"id":1,"identifier":"admin","name":"관리자"}]	사용자에게 부여된 역할 목록 (원소: id/identifier/name — 역할 관계 파생)
permissions	array	[]	연결된 권한 목록 (id/identifier/name — 역할 경유 권한 관계 파생)
consents	array	[]	사용자가 동의한 약관 동의 레코드 목록 (약관 관계 파생)
terms_consent	null	null	이용약관 동의 정보 (동의 시각 등, 미동의 시 null)
privacy_consent	null	null	개인정보 처리방침 동의 정보 (동의 시각 등, 미동의 시 null)
created_at	string	2026-07-06 19:15:16	생성 일시
updated_at	string	2026-07-06 19:15:16	최종 수정 일시
is_owner	boolean	true	현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타)
abilities	object	{"can_read":true,"can_create":true,"can_update":true,"can…	현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반)
admin_memo	string	Perferendis ut suscipit quia unde sed.	관리자 메모
ip_address	string	77.105.222.87	마지막 접속 IP 주소
withdrawn_at	null	null	withdrawn 일시
blocked_at	null	null	blocked 일시
notify_post_complete	boolean	false	게시글 작성 완료 알림 수신 여부 (게시판 모듈 알림 설정)
notify_post_reply	boolean	false	내 게시글 답글 알림 수신 여부
notify_comment	boolean	false	내 게시글 댓글 알림 수신 여부
notify_reply_comment	boolean	false	내 댓글 대댓글 알림 수신 여부
email_subscription	boolean	false	광고성 이메일 수신 동의 여부 (marketing 플러그인 채널 동의)
email_subscription_at	null	null	email subscription 일시
marketing_consent	boolean	false	마케팅 정보 수신 전체 동의 여부 (marketing 플러그인 마스터 키, 미동의 시 false)
marketing_consent_at	null	null	marketing consent 일시
third_party_consent	boolean	false	제3자 정보 제공 동의 여부 (marketing 플러그인 법적 동의 항목)
third_party_consent_at	null	null	third party consent 일시
info_disclosure	boolean	false	개인정보 이용 안내 동의 여부 (marketing 플러그인 법적 동의 항목)
info_disclosure_at	null	null	info disclosure 일시
marketing_consent_enabled	boolean	true	마케팅 동의 UI 노출 여부 (marketing 플러그인 활성화 플래그, 기본 true)
marketing_consent_terms_slug	string	marketing-terms	마케팅 약관 slug (연결된 약관 페이지 식별자, 미설정 시 null)
marketing_consent_terms_slug_set	boolean	true	마케팅 약관 연결 존재 여부 (프론트 약관 링크 표시 판정용)
third_party_consent_enabled	boolean	true	제3자 제공 동의 항목 노출 여부 (marketing 플러그인 활성화 플래그)
third_party_consent_terms_slug	null	null	제3자 제공 약관 slug (미설정 시 null)
third_party_consent_terms_slug_set	boolean	false	제3자 제공 약관 연결 존재 여부
info_disclosure_enabled	boolean	true	정보 이용 안내 동의 항목 노출 여부 (marketing 플러그인 활성화 플래그)
info_disclosure_terms_slug	null	null	정보 이용 안내 약관 slug (미설정 시 null)
info_disclosure_terms_slug_set	boolean	false	정보 이용 안내 약관 연결 존재 여부
email_subscription_enabled	boolean	true	이메일 수신 채널 노출 여부 (marketing 플러그인 활성화 플래그)
email_subscription_terms_slug	null	null	이메일 수신 약관 slug (미설정 시 null)
email_subscription_terms_slug_set	boolean	false	이메일 수신 약관 연결 존재 여부
channels	array	[{"key":"email_subscription","label":"광고성 이메일 수신","enable…	관리자 정의 전체 마케팅 채널 목록 (원소: key/label/enabled/terms_slug — marketing 플러그인 주입, iteration 렌더링용)
consent_histories	array	[]	사용자 동의 변경 이력 (원소: channel_key/action/source/created_at — marketing 플러그인 주입)
ecommerce_mileage	object	{"enabled":false}	이커머스 마일리지 정보 (enabled 및 잔액 등 — sirsoft-ecommerce 모듈 주입)
ecommerce_preferred_currency	null	null	선호 결제 통화 (sirsoft-ecommerce 모듈 주입, 미설정 시 null)
ecommerce_preferred_shipping_country	null	null	선호 배송 국가 코드 (sirsoft-ecommerce 모듈 주입, 미설정 시 null)
ecommerce_preferred_shipping_country_name	null	null	선호 배송 국가명 (배송 국가 코드에서 파생, sirsoft-ecommerce 모듈 주입)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.read)이 없는 경우
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

특정 사용자의 상세 정보를 조회합니다(경로 파라미터는 UUID 로 바인딩). withAdminInfo() 를 통해 기본 필드에 더해 관리자 전용 필드(admin_memo, ip_address, withdrawn_at, blocked_at)와 관계형 데이터(modules, plugins, menus, roles, permissions, consents 및 개수 필드)를 함께 반환한다. core.user.filter_resource_data 필터로 확장이 자신의 필드(sirsoft-marketing 의 알림/동의 설정, sirsoft-ecommerce 의 마일리지/선호 통화·배송국 등)를 병합한다. 관리자 사용자 상세/수정 화면(admin_user_detail.json/admin_user_form.json)이 소비한다.

PUT /api/admin/users/{user}

• 라우트명: api.admin.users.update
• 컨트롤러: App\Http\Controllers\Api\Admin\UserController@update
• 인증/권한: auth:sanctum + permission:core.users.update

요청 파라미터

이름	위치	타입	필수	허용값	용도
user	path	string	예	—	대상 user의 식별자
name	body	string	예	max 255	대상의 이름/명칭
nickname	body	string	아니오	max 50	닉네임
email	body	email	예	max 255	이메일 주소
password	body	string	아니오	—	비밀번호
language	body	string	아니오	ko, en, fr, ja	언어 코드
country	body	string	아니오	—	국가 코드 (ISO 3166-1 alpha-2)
timezone	body	string	아니오	—	타임존 식별자
status	body	string	아니오	active, inactive, blocked, withdrawn	계정 상태 (미지정 시 active)
homepage	body	string	아니오	max 255	홈페이지 URL
mobile	body	string	아니오	max 20	휴대전화 번호
phone	body	string	아니오	max 20	전화번호
zipcode	body	string	아니오	max 10	우편번호
address	body	string	아니오	max 255	기본 주소
address_detail	body	string	아니오	max 255	상세 주소
signature	body	string	아니오	max 1000	서명
bio	body	string	아니오	max 5000	자기소개
admin_memo	body	string	아니오	max 5000	관리자 전용 메모 (해당 사용자에 대한 내부 기록, 사용자에게 노출 안 됨)
roles	body	array	아니오	min 1	부여할 역할 객체 배열 [{id}] (role_ids 와 병용 시 role_ids 우선)
role_ids	body	array	아니오	min 1	role 식별자 배열
notify_post_complete	body	boolean	아니오	—	게시글 작성 완료 알림 수신 여부 (게시판 모듈 알림 설정)
notify_post_reply	body	boolean	아니오	—	내 게시글에 답글이 달릴 때 알림 수신 여부
notify_comment	body	boolean	아니오	—	내 게시글에 댓글이 달릴 때 알림 수신 여부
notify_reply_comment	body	boolean	아니오	—	내 댓글에 대댓글이 달릴 때 알림 수신 여부
email_subscription	body	boolean	아니오	—	광고성 이메일 수신 동의 여부 (marketing 플러그인 채널 동의, marketing_consents 테이블에 저장)
marketing_consent	body	boolean	아니오	—	마케팅 정보 수신 전체 동의 마스터 키 (marketing 플러그인이 검증 규칙 주입, 상세는 user-consent-injection.md)
third_party_consent	body	boolean	아니오	—	제3자 정보 제공 동의 여부 (marketing 플러그인 법적 동의 항목)
info_disclosure	body	boolean	아니오	—	개인정보 이용 안내 동의 여부 (marketing 플러그인 법적 동의 항목)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.user.update_validation_rules).

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
403	Forbidden	요구 권한(core.users.update)이 없는 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

기존 사용자 정보를 수정합니다(경로 파라미터는 UUID 로 바인딩). name, email 은 필수이며 email 은 해당 사용자를 제외한 고유성 검사를 거친다. password 는 선택이며 값을 주면 8자 이상·password_confirmation 확인을 요구한다(미전송 시 기존 비밀번호 유지). 역할은 roles 또는 role_ids 중 하나로 지정하고 둘 다 오면 role_ids 가 우선한다. 성공 시 갱신된 사용자를 UserResource 로 반환한다. notify_*/marketing_consent/third_party_consent/info_disclosure/email_subscription 파라미터는 확장(sirsoft-marketing)이 검증 규칙을 주입한 필드로, 상세는 해당 확장 문서를 참조한다.

GET /api/users/{user}/profile

• 라우트명: api.public.users.profile
• 컨트롤러: App\Http\Controllers\Api\Public\PublicProfileController@show
• 인증/권한: 공개 (인증 불필요)

요청 파라미터

이름	위치	타입	필수	허용값	용도
user	path	string	예	—	대상 user의 식별자

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드	타입	실측 예시값	용도/설명
uuid	string	a231747f-e82e-4cf2-9ae1-a261849dce40	외부 노출용 UUID (URL/API 식별자, 내부 id 비노출)
name	string	API 문서 샘플 사용자	사용자 이름
status	string	active	계정 상태 (active: 활성, inactive: 비활성, blocked: 차단, withdrawn: 탈퇴)
status_label	string	활성	상태의 사람이 읽는 라벨 (상태 Enum label() 산물)
avatar	null	null	프로필 아바타 이미지 URL (미설정 시 null)
bio	string	Tenetur omnis et amet omnis veniam to…	자기소개
created_at	string	2026-07-06	생성 일시
is_withdrawn	boolean	false	withdrawn 여부

에러 응답

상태코드	의미	발생 조건
404	Not Found	path 파라미터에 해당하는 리소스가 없는 경우

설명

타인의 공개 프로필을 인증 없이 조회합니다(경로 파라미터는 UUID 로 바인딩, users/show.json 이 소비). 사용자 상태에 따라 노출 필드가 달라진다 — active 는 name/avatar/bio/created_at 전체, inactive 는 bio 를 제외, blocked 는 avatar/bio/created_at 를 모두 제외한다. withdrawn 사용자는 이름을 익명 표기로 대체하고 is_withdrawn=true 로 반환하며, 미존재 사용자는 404(user.not_found)를 반환한다. 게시글 통계는 게시판 모듈 API 로 별도 조회한다.