HeuJung
b5c0ec1178
관리자 상품목록을 한 페이지 여는 것만으로 그 페이지 모든 상품의 옵션이 응답에 실렸다. 같은 패턴을 저장소 전역에서 찾아 14개 목록 엔드포인트를 함께 정리했다. 근본 원인은 둘이다. Resource 가 whenLoaded 로 방어하는데 Repository 가 목록 쿼리에서 관계를 무조건 로드해 가드가 항상 참이 되는 가짜 가드, 그리고 toListArray 경량 표현을 정의해 두고도 컬렉션이 toArray 를 부르는 목록/상세 미분리다. 둘 다 응답만 보면 정상이라 오류도 경고도 없이 페이로드만 불어난다. 목록은 화면이 실제로 그리는 것만 싣는다. 개수·합계는 PHP 컬렉션 연산이 아니라 DB 집계로, 대표 1건이 필요한 곳은 관계 자체를 oldestOfMany 로 좁힌다. eager load 의 limit(1) 은 부모별이 아니라 배치 쿼리 전체에 걸려 첫 행만 값을 갖게 되므로 쓸 수 없다. 뺀 값에는 대체 경로를 먼저 만들었다. 상품 옵션은 행을 펼칠 때 배치로 불러오고(상품 수와 무관하게 쿼리 상수), 종전 동작이 필요한 호출자를 위해 ?with_options=1 등 opt-in 을 남겼다. 배송정책 국가설정과 리뷰 첨부 이미지는 소비처를 실측한 결과 화면이 실제로 그리고 있어 제거하지 않았다 — 그 소비 사실을 회귀 테스트로 고정했다. 재발 방지로 정적 검사 룰 4종과 규정 문서 항목을 함께 넣었다.
42 KiB
Auth API 레퍼런스
소유: 코어 · 생성:
php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Auth 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
POST /api/admin/auth/logout
- 라우트명:
api.admin.auth.logout - 컨트롤러:
App\Http\Controllers\Api\Admin\AuthController@logout - 인증/권한:
auth:sanctum
요청 파라미터
요청 파라미터 없음.
요청 예시
POST /api/admin/auth/logout HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "로그아웃이 성공했습니다.",
"data": null
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
설명
현재 관리자의 Sanctum 토큰을 폐기해 로그아웃한다. AuthService::logout() 이 3단계(토큰 삭제 → 세션 무효화 → Auth::logout())를 수행하며, data 는 없고 message 만 auth.logout_success 로 내려온다. 프론트는 응답 후 저장된 Bearer 토큰을 폐기하고 로그인 화면으로 전환한다.
POST /api/admin/auth/refresh
- 라우트명:
api.admin.auth.refresh - 컨트롤러:
App\Http\Controllers\Api\Admin\AuthController@refresh - 인증/권한:
auth:sanctum
요청 파라미터
요청 파라미터 없음.
요청 예시
POST /api/admin/auth/refresh HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| user | object | {"uuid":"a26219fc-94a0-4f63-9404-04c2a6ac99e4","name":"최고… |
대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생) |
| token | string | 380|ZjZl46uRlhHt53MEhb7XAb0r5lYoDEsXF… |
발급된 API 접근 토큰 평문 (Bearer 토큰으로 사용, 발급 시 1회만 노출) |
| token_type | string | Bearer |
토큰 타입 (일반적으로 Bearer) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "성공적으로 처리되었습니다.",
"data": {
"user": {
"uuid": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
"name": "최고관리자",
"nickname": "최고관리자",
"email": "heuristing@gmail.com",
"avatar": null,
"language": "ko",
"language_label": "한국어",
"country": null,
"status": "active",
"status_label": "활성",
"status_variant": "success",
"is_admin": true,
"homepage": null,
"mobile": null,
"phone": null,
"zipcode": null,
"address": null,
"address_detail": null,
"signature": null,
"bio": null,
"last_login_at": "2026-08-04 19:00:10",
"email_verified_at": "2026-07-30 23:37:44",
"timezone": "Asia/Seoul",
"created_at": "2026-07-30 23:37:44",
"updated_at": "2026-08-04 19:00:10",
"is_owner": true,
"abilities": {
"can_read": true,
"can_create": true,
"can_update": true,
"can_delete": false,
"can_assign_roles": true
}
},
"token": "{MASKED}",
"token_type": "Bearer"
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
설명
현재 관리자 토큰을 새 Sanctum 토큰으로 교체한다. AuthService::refreshToken() 이 기존 토큰을 폐기하고 새 토큰을 발급하며, data 에는 새 token 과 user(UserResource) 가 담긴다. 만료 임박 토큰을 재발급하는 용도로, 세션 만료로 재인증이 필요한 경우(토큰 무효)에는 401 auth.unauthenticated 를 반환한다.
GET /api/admin/auth/user
- 라우트명:
api.admin.auth.user - 컨트롤러:
App\Http\Controllers\Api\Admin\AuthController@user - 인증/권한:
auth:sanctum
요청 파라미터
요청 파라미터 없음.
요청 예시
GET /api/admin/auth/user HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| uuid | string | a26219fc-94a0-4f63-9404-04c2a6ac99e4 |
외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
| name | string | 최고관리자 |
사용자 이름 |
| nickname | string | 최고관리자 |
닉네임 |
| string | heuristing@gmail.com |
이메일 주소 | |
| avatar | null | null |
아바타 이미지 URL (User::getAvatarUrl() — 아바타 미설정 시 null) |
| language | string | ko |
사용자 언어 설정 (ko: 한국어, en: 영어) |
| language_label | string | 한국어 |
언어 코드의 현지화 라벨 (user.language.{code} 번역) |
| country | null | null |
국가 코드 (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 | null | null |
홈페이지 URL |
| mobile | null | null |
휴대폰 번호 |
| phone | null | null |
전화번호 |
| zipcode | null | null |
우편번호 |
| address | null | null |
기본 주소 |
| address_detail | null | null |
상세 주소 |
| signature | null | null |
서명 |
| bio | null | null |
자기소개 |
| last_login_at | string | 2026-08-04 19:00:10 |
last login 일시 |
| email_verified_at | string | 2026-07-30 23:37:44 |
email verified 일시 |
| timezone | string | Asia/Seoul |
사용자 시간대 (예: Asia/Seoul, UTC) |
| roles | array | [{"id":1,"identifier":"admin","name":"관리자"}] |
사용자에게 부여된 역할 목록 (원소 id/identifier/name — roles 관계 파생, name 은 현지화 라벨) |
| permissions | array | [{"id":2,"identifier":"sirsoft-ecommerce.user-products.re… |
연결된 권한 목록 (id/identifier/name — 역할 경유 권한 관계 파생) |
| created_at | string | 2026-07-30 23:37:44 |
생성 일시 |
| updated_at | string | 2026-08-04 19:00:10 |
최종 수정 일시 |
| is_owner | boolean | true |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_create":true,"can_update":true,"can… |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "성공적으로 처리되었습니다.",
"data": {
"uuid": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
"name": "최고관리자",
"nickname": "최고관리자",
"email": "heuristing@gmail.com",
"avatar": null,
"...": "(24개 키 생략, 총 29개)"
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
설명
관리자 레이아웃 전역 부트스트랩 엔드포인트. _admin_base.json 의 data_source(current_user)가 모든 관리자 페이지 진입 시 자동 호출해, 헤더/권한 게이트/is_admin 분기의 기준 사용자 정보를 채운다. 응답에는 roles.permissions 가 eager load 되어 permissions 배열이 함께 내려온다.
인증 계약: auth:sanctum 필요 — Bearer 토큰이 없거나 만료되면 401 을 반환한다(프론트 data_source 의 auth_required: true 에 대응). 이 계약이 프론트 소비의 SSoT 이므로 미들웨어 체인 변경 시 반드시 프론트 auth_required/auth_mode 와 함께 검토한다(이슈 #64).
POST /api/auth/admin/login
- 라우트명:
api.auth.admin.login - 컨트롤러:
App\Http\Controllers\Api\Admin\AuthController@login - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| body | 예 | — | 이메일 주소 | ||
| password | body | string | 예 | — | 비밀번호 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.login_validation_rules).
요청 예시
POST /api/auth/admin/login HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"email": "user@example.com",
"password": "Password123!"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
관리자 로그인. email/password 검증 후 AuthService::login() 이 인증하고, 인증 사용자가 isAdmin() 이 아니면 403 auth.admin_required 로 거부한다. 성공 시 data.token(Sanctum Bearer) 과 data.user(UserResource) 를 반환한다. 계정 잠금 시 AccountLockedException, 자격 불일치 시 422 검증 오류를 반환한다. 이후 모든 관리자 API 호출은 이 토큰을 Authorization: Bearer 헤더로 실어야 한다.
POST /api/auth/forgot-password
- 라우트명:
api.auth.forgot-password - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@forgotPassword - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| body | 예 | — | 이메일 주소 | ||
| redirect_prefix | body | string | 아니오 | admin |
재설정 링크가 향할 화면 구분값 — admin 전달 시 관리자 재설정 화면, 미지정 시 사용자 화면 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.forgot_password_validation_rules).
요청 예시
POST /api/auth/forgot-password HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"email": "user@example.com",
"redirect_prefix": "admin"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
비밀번호 재설정 메일 발송을 요청한다(공개). email 로 계정을 찾아 재설정 링크 메일을 보내고 message: auth.password_reset_email_sent 를 반환한다. redirect_prefix 는 재설정 링크가 향할 화면을 구분하는 값으로 관리자 흐름(admin_forgot_password.json)에서는 admin 을 전달해 링크가 관리자 재설정 화면을 가리키게 한다(미지정 시 사용자 화면). 계정 열거 방지를 위해 이메일 존재 여부와 무관하게 동일 응답을 주는 것이 원칙이다.
POST /api/auth/login
- 라우트명:
api.auth.login - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@login - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| body | 예 | — | 이메일 주소 | ||
| password | body | string | 예 | — | 비밀번호 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.login_validation_rules).
요청 예시
POST /api/auth/login HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"email": "user@example.com",
"password": "Password123!"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
일반 사용자 로그인(공개). 관리자 로그인과 달리 isAdmin() 검사가 없다. 성공 시 data.token(Sanctum Bearer) 과 data.user 를 반환하며 message: auth.login_success. 계정 잠금 시 423 auth.account_locked 를 잠금 해제까지 남은 정보(errors.locked_until, errors.retry_after_seconds)와 함께 반환한다. 보안 환경설정의 잠금 시간이 0(무한대)이면 무기한 잠금이 되어 423 auth.account_locked_permanently 와 함께 errors.permanent=true, errors.locked_until=null, errors.retry_after_seconds=null 을 반환하며 Retry-After 헤더도 붙지 않는다. 이 경우 해제 수단은 관리자 해제 API(POST /api/admin/users/{user}/unlock) 뿐이다. 프론트 로그인 폼(partials/auth/_register_form.json 인접)에서 소비한다.
2단계 인증이 켜져 있는 경우: 보안 환경설정 security.two_factor_auth 가 켜져 있으면 비밀번호가 맞아도 토큰을 발급하지 않는다. 대신 200 과 함께 message: auth.two_factor_required 및 아래 필드를 반환하며, 클라이언트는 POST /api/auth/login/two-factor 로 코드를 확인해야 로그인이 완료된다.
| 필드 | 타입 | 설명 |
|---|---|---|
two_factor_required |
boolean | 항상 true — 이 응답이 추가 확인 단계임을 나타낸다 |
challenge_id |
string(uuid) | 확인 단계에 그대로 전달할 challenge 식별자 |
provider_id |
string | 코드를 발송한 본인인증 프로바이더 |
expires_at |
string(ISO8601)|null | challenge 만료 시각 |
이 응답에는 data.token 과 data.user 가 없다. 토큰 존재 여부로 로그인 완료를 판정하는 클라이언트는 그대로 동작한다.
POST /api/auth/login/two-factor
- 라우트명:
api.auth.login.two-factor - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@verifyTwoFactor - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| challenge_id | body | string | 예 | — | 로그인 응답이 돌려준 challenge 식별자 |
| code | body | string | 예 | min 4, max 16 | 사용자가 받은 인증 코드 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.two_factor_validation_rules).
요청 예시
POST /api/auth/login/two-factor HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"challenge_id": "예시값",
"code": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | challenge_id/code 형식 위반 |
설명
비밀번호 단계가 돌려준 challenge 를 확인해 로그인을 완료한다. 로그인과 동일한 요청 제한(throttle:auth-login)이 걸려 코드 대입 시도도 함께 억제된다.
challenge 의 purpose 가 login 인지 먼저 대조한다 — 대조하지 않으면 회원가입·비밀번호 재설정 등 다른 흐름에서 발급된 challenge 로 로그인할 수 있다. 코드 확인에 성공하기 전에는 어떤 경우에도 토큰이 발급되지 않는다.
POST /api/auth/logout
- 라우트명:
api.auth.logout - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@logout - 인증/권한:
auth:sanctum
요청 파라미터
요청 파라미터 없음.
요청 예시
POST /api/auth/logout HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "로그아웃이 성공했습니다.",
"data": null
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
설명
현재 사용자 토큰을 폐기해 로그아웃한다(message: auth.logout_success). 현재 요청에 사용된 토큰만 폐기하며, 모든 기기에서 로그아웃하려면 /api/user/auth/logout-all-devices 를 사용한다.
POST /api/auth/register
- 라우트명:
api.auth.register - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@register - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| name | body | string | 예 | max 255 | 대상의 이름/명칭 |
| nickname | body | string | 아니오 | max 50 | 닉네임 |
| body | string | 예 | max 255 | 이메일 주소 | |
| password | body | string | 예 | — | 비밀번호 |
| mobile | body | string | 아니오 | max 20 | 휴대폰번호 (선택) |
| phone | body | string | 아니오 | max 20 | 전화번호 (선택) |
| language | body | string | 아니오 | ko, en |
언어 코드 |
| agree_terms | body | string | 아니오 | — | 이용약관 동의 (코어 필수 동의 — accepted 규칙, 미동의 시 가입 거부) |
| agree_privacy | body | string | 아니오 | — | 개인정보 처리방침 동의 (코어 필수 동의 — accepted 규칙, 미동의 시 가입 거부) |
| agree_email_subscription | body | boolean | 아니오 | — | 광고성 이메일 수신 동의 (marketing 플러그인 주입, 선택 항목) |
| agree_marketing_consent | body | boolean | 아니오 | — | 마케팅 정보 수신 전체 동의 (marketing 플러그인 주입, 선택 항목) |
| agree_third_party_consent | body | boolean | 아니오 | — | 제3자 정보 제공 동의 (marketing 플러그인 주입, 선택 항목) |
| agree_info_disclosure | body | boolean | 아니오 | — | 개인정보 이용 안내 동의 (marketing 플러그인 주입, 선택 항목) |
| preferred_currency | body | string | 아니오 | — | 선호 결제 통화 (ecommerce 모듈 주입, 가입 시 계정 기본 통화로 저장) |
| preferred_shipping_country | body | string | 아니오 | — | 선호 배송 국가 코드 (ecommerce 모듈 주입, 가입 시 계정 기본 배송 국가로 저장) |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.register_validation_rules).
요청 예시
POST /api/auth/register HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"name": "예시 이름",
"nickname": "예시 이름",
"email": "user@example.com",
"password": "Password123!",
"mobile": "010-1234-5678",
"phone": "010-1234-5678",
"language": "ko",
"agree_terms": "예시값",
"agree_privacy": "예시값",
"agree_email_subscription": true,
"agree_marketing_consent": true,
"agree_third_party_consent": true,
"agree_info_disclosure": true,
"preferred_currency": "예시값",
"preferred_shipping_country": "KR"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
회원가입(공개). 성공 시 201 auth.register_success 와 data.token/data.user 를 반환해 가입 직후 로그인 상태로 이어진다. agree_* 동의 파라미터(약관/개인정보/이메일수신/마케팅/제3자제공/정보공개)는 가입 시점의 동의 이력으로 기록된다 — 그중 agree_email_subscription/agree_marketing_consent/agree_third_party_consent/agree_info_disclosure 및 preferred_currency/preferred_shipping_country 는 marketing·ecommerce 확장이 훅(core.auth.register_validation_rules)으로 주입하는 파라미터로, 해당 확장 비활성 시 무시된다. 검증 실패 시 422 auth.register_failed.
POST /api/auth/reset-password
- 라우트명:
api.auth.reset-password - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@resetPassword - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| token | body | string | 예 | — | 인증/검증 토큰 |
| body | 예 | — | 이메일 주소 | ||
| password | body | string | 예 | — | 비밀번호 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.reset_password_validation_rules).
요청 예시
POST /api/auth/reset-password HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"token": "{YOUR_TOKEN}",
"email": "user@example.com",
"password": "Password123!"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
비밀번호 재설정을 실제 반영한다(공개). 재설정 메일의 token 과 email, 새 password 를 받아 비밀번호를 갱신하고 message: auth.password_reset_success. 토큰 만료/불일치 등 검증 실패 시 422 auth.password_reset_failed. 반영 전 토큰 유효성만 먼저 확인하려면 /api/auth/validate-reset-token 을 사용한다.
GET /api/auth/user
- 라우트명:
api.auth.user - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@user - 인증/권한:
auth:sanctum
요청 파라미터
요청 파라미터 없음.
요청 예시
GET /api/auth/user HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| uuid | string | a26219fc-94a0-4f63-9404-04c2a6ac99e4 |
외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
| name | string | 최고관리자 |
사용자 이름 |
| nickname | string | 최고관리자 |
닉네임 |
| string | heuristing@gmail.com |
이메일 주소 | |
| avatar | null | null |
아바타 이미지 URL (User::getAvatarUrl() — 아바타 미설정 시 null) |
| language | string | ko |
사용자 언어 설정 (ko: 한국어, en: 영어) |
| language_label | string | 한국어 |
언어 코드의 현지화 라벨 (user.language.{code} 번역) |
| country | null | null |
국가 코드 (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 | null | null |
홈페이지 URL |
| mobile | null | null |
휴대폰 번호 |
| phone | null | null |
전화번호 |
| zipcode | null | null |
우편번호 |
| address | null | null |
기본 주소 |
| address_detail | null | null |
상세 주소 |
| signature | null | null |
서명 |
| bio | null | null |
자기소개 |
| last_login_at | string | 2026-08-04 19:00:10 |
last login 일시 |
| email_verified_at | string | 2026-07-30 23:37:44 |
email verified 일시 |
| timezone | string | Asia/Seoul |
사용자 시간대 (예: Asia/Seoul, UTC) |
| modules_count | array | [] |
접근 가능 모듈 수 (modules_count 속성이 로드된 경우에만 포함 — whenLoaded 성격의 조건부 필드) |
| plugins_count | array | [] |
접근 가능 플러그인 수 (plugins_count 속성이 로드된 경우에만 포함) |
| menus_count | array | [] |
접근 가능 메뉴 수 (menus_count 속성이 로드된 경우에만 포함) |
| modules | array | [] |
접근 가능 모듈 목록 (원소 id/name/slug/is_active — modules 관계 로드 시에만 포함) |
| plugins | array | [] |
접근 가능 플러그인 목록 (원소 id/name/slug/is_active — plugins 관계 로드 시에만 포함) |
| menus | array | [] |
접근 가능 메뉴 목록 (원소 id/title/url/is_active — menus 관계 로드 시에만 포함) |
| roles | array | [{"id":1,"identifier":"admin","name":"관리자"}] |
사용자에게 부여된 역할 목록 (원소 id/identifier/name — roles 관계 파생, name 은 현지화 라벨) |
| permissions | array | [{"id":2,"identifier":"sirsoft-ecommerce.user-products.re… |
연결된 권한 목록 (id/identifier/name — 역할 경유 권한 관계 파생) |
| consents | array | [] |
전체 약관 동의 이력 (원소 consent_type/agreed_at/revoked_at — consents 관계 로드 시 포함, 플러그인 참조용) |
| terms_consent | array | [] |
이용약관 동의 정보 (agreed_at — ConsentType::Terms 동의 이력에서 파생, 미동의 시 null) |
| privacy_consent | array | [] |
개인정보 처리방침 동의 정보 (agreed_at — ConsentType::Privacy 동의 이력에서 파생, 미동의 시 null) |
| created_at | string | 2026-07-30 23:37:44 |
생성 일시 |
| updated_at | string | 2026-08-04 19:00:10 |
최종 수정 일시 |
| is_owner | boolean | true |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_create":true,"can_update":true,"can… |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
| notify_post_complete | boolean | false |
게시판 새 글 작성 완료 알림 수신 설정 (marketing 플러그인 주입) |
| notify_post_reply | boolean | false |
내 게시글에 답글 달림 알림 수신 설정 (marketing 플러그인 주입) |
| notify_comment | boolean | false |
내 게시글에 댓글 달림 알림 수신 설정 (marketing 플러그인 주입) |
| notify_reply_comment | boolean | false |
내 댓글에 답글 달림 알림 수신 설정 (marketing 플러그인 주입) |
| email_subscription | boolean | false |
광고성 이메일 수신 동의 여부 (marketing 플러그인 주입) |
| email_subscription_at | null | null |
email subscription 일시 (광고성 이메일 수신 동의 시각, 미동의 시 null) |
| marketing_consent | boolean | false |
마케팅 정보 수신 전체 동의 마스터 키 (marketing 플러그인 주입) |
| marketing_consent_at | null | null |
marketing consent 일시 (마케팅 정보 수신 동의 시각, 미동의 시 null) |
| third_party_consent | boolean | false |
제3자 정보 제공 동의 여부 (법적 항목 — marketing 플러그인 주입) |
| third_party_consent_at | null | null |
third party consent 일시 (제3자 정보 제공 동의 시각, 미동의 시 null) |
| info_disclosure | boolean | false |
개인정보 이용 안내 동의 여부 (법적 항목 — marketing 플러그인 주입) |
| info_disclosure_at | null | null |
info disclosure 일시 (개인정보 이용 안내 동의 시각, 미동의 시 null) |
| marketing_consent_enabled | boolean | true |
마케팅 정보 수신 동의 항목 UI 노출 여부 (관리자 활성화 플래그) |
| marketing_consent_terms_slug | string | marketing-terms |
마케팅 정보 수신 동의에 연결된 약관 slug (미설정 시 null) |
| marketing_consent_terms_slug_set | boolean | true |
마케팅 정보 수신 약관 연결 존재 여부 (프론트 링크 표시 판정용) |
| third_party_consent_enabled | boolean | true |
제3자 정보 제공 동의 항목 UI 노출 여부 (관리자 활성화 플래그) |
| third_party_consent_terms_slug | null | null |
제3자 정보 제공 동의에 연결된 약관 slug (미설정 시 null) |
| third_party_consent_terms_slug_set | boolean | false |
제3자 정보 제공 약관 연결 존재 여부 (프론트 링크 표시 판정용) |
| info_disclosure_enabled | boolean | true |
개인정보 이용 안내 동의 항목 UI 노출 여부 (관리자 활성화 플래그) |
| info_disclosure_terms_slug | null | null |
개인정보 이용 안내 동의에 연결된 약관 slug (미설정 시 null) |
| info_disclosure_terms_slug_set | boolean | false |
개인정보 이용 안내 약관 연결 존재 여부 (프론트 링크 표시 판정용) |
| email_subscription_enabled | boolean | true |
광고성 이메일 수신 동의 항목 UI 노출 여부 (관리자 활성화 플래그) |
| 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 플러그인 주입) |
| consent_histories | array | [] |
동의 변경 이력 (원소 channel_key/action/source/created_at — marketing 플러그인 주입) |
| ecommerce_mileage | object | {"enabled":false} |
마일리지 정보 (enabled/잔액 — ecommerce 모듈 주입, 모듈 비활성 시 enabled=false) |
| ecommerce_preferred_currency | null | null |
선호 결제 통화 (ecommerce 모듈 주입, 미설정 시 null) |
| ecommerce_preferred_shipping_country | null | null |
선호 배송 국가 코드 (ecommerce 모듈 주입, 미설정 시 null) |
| ecommerce_preferred_shipping_country_name | null | null |
선호 배송 국가 이름 (국가 코드에서 현지화 파생 — ecommerce 모듈 주입, 미설정 시 null) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "성공적으로 처리되었습니다.",
"data": {
"uuid": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
"name": "최고관리자",
"nickname": "최고관리자",
"email": "heuristing@gmail.com",
"avatar": null,
"...": "(63개 키 생략, 총 68개)"
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
설명
프론트(사용자) 레이아웃 전역 부트스트랩 엔드포인트. _user_base.json 의 current_user data_source 가 모든 페이지 진입 시 호출한다. 관리자 user 와 달리 응답을 UserResource::toAuthArray() 로 만들어 core.user.filter_resource_data 필터를 적용하므로, marketing 플러그인·ecommerce 모듈이 훅으로 병합한 필드(notify_*, marketing_consent*, channels, ecommerce_* 등)가 함께 내려온다. 이 필드들은 확장 소유이므로 상세 설명은 각 확장 문서를 따른다. 로그인 시 이 응답이 계정 영속 통화를 덮어쓰는 계약(D-LOGIN-CUR)의 출처다.
인증 계약: 이 경로(api.auth.user)는 auth:sanctum 으로 인증이 필수다. 인증 여부와 무관하게 게스트 컨텍스트가 필요한 화면은 optional.sanctum 이 걸린 /api/user/auth/user(api.user.auth.user)를 사용해야 한다 — 프론트 data_source 의 auth_mode: "optional" 이 이 경로에 대응한다. 두 경로의 미들웨어 차이가 곧 auth_required/auth_mode 계약이므로 변경 시 프론트와 함께 검토한다(이슈 #64).
POST /api/auth/validate-reset-token
- 라우트명:
api.auth.validate-reset-token - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@validateResetToken - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| token | body | string | 예 | — | 인증/검증 토큰 |
| body | 예 | — | 이메일 주소 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
core.auth.validate_reset_token_messages).
요청 예시
POST /api/auth/validate-reset-token HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"token": "{YOUR_TOKEN}",
"email": "user@example.com"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
비밀번호 재설정 토큰의 유효성만 사전 확인한다(공개, 비밀번호 미변경). 재설정 화면(admin_reset_password.json/auth/reset_password.json) 진입 시 토큰/이메일이 유효한지 먼저 검사해, 만료·위조 링크면 즉시 오류 화면을 보이고 유효하면 새 비밀번호 입력 폼을 노출하는 용도다. 실제 반영은 /api/auth/reset-password 가 담당한다.
POST /api/user/auth/logout
- 라우트명:
api.user.auth.logout - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@logout - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:core.auth.logout
요청 파라미터
요청 파라미터 없음.
요청 예시
POST /api/user/auth/logout HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 403 | Forbidden | 요구 권한(core.auth.logout)이 없는 경우 |
설명
/user prefix 그룹의 사용자 로그아웃. 공용 경로 /api/auth/logout 과 동일하게 현재 토큰을 폐기하되, permission:core.auth.logout 권한 게이트를 추가로 통과해야 한다. 세션 시작(start.api.session)이 걸린 공용 경로와 달리 권한 기반 접근 제어가 필요한 흐름에서 사용한다.
POST /api/user/auth/logout-all-devices
- 라우트명:
api.user.auth.logout-all-devices - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@logoutFromAllDevices - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:core.auth.logout
요청 파라미터
요청 파라미터 없음.
요청 예시
POST /api/user/auth/logout-all-devices HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 403 | Forbidden | 요구 권한(core.auth.logout)이 없는 경우 |
설명
현재 사용자의 모든 Sanctum 토큰을 폐기해 전 기기에서 로그아웃한다(message: auth.logout_all_devices_success). 비밀번호 변경 후 기존 세션 무효화, 계정 도용 대응 등에 사용한다.
POST /api/user/auth/refresh
- 라우트명:
api.user.auth.refresh - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@refresh - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:core.auth.refresh
요청 파라미터
요청 파라미터 없음.
요청 예시
POST /api/user/auth/refresh HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 403 | Forbidden | 요구 권한(core.auth.refresh)이 없는 경우 |
설명
/user prefix 그룹의 토큰 갱신. 공용 refresh 와 동작은 같으나 permission:core.auth.refresh 권한 게이트를 추가로 통과해야 한다. 이 그룹(routes/api.php:271)은 optional.sanctum + RefreshTokenExpiration 미들웨어 아래 있어 토큰 만료 정책 갱신과 함께 동작한다.
GET /api/user/auth/user
- 라우트명:
api.user.auth.user - 컨트롤러:
App\Http\Controllers\Api\Auth\AuthController@user - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:core.auth.user
요청 파라미터
요청 파라미터 없음.
요청 예시
GET /api/user/auth/user HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 403 | Forbidden | 요구 권한(core.auth.user)이 없는 경우 |
설명
/user prefix 그룹(routes/api.php:271)의 현재 사용자 정보. 이 그룹은 optional.sanctum 미들웨어 아래 있어 비인증(게스트) 요청도 통과하며, 게스트 컨텍스트가 필요한 프론트 화면의 data_source(auth_mode: "optional")가 이 경로를 소비한다. 응답 필드는 인증된 경우 공용 /api/auth/user 와 동일 형태(toAuthArray 병합 포함)이며, 이 경로에는 추가로 permission:core.auth.user 권한 게이트가 걸린다. 실측이 403 으로 제외된 것은 샘플 사용자에 해당 권한이 없었기 때문으로, 응답 shape 은 공용 user 경로를 참조한다.
인증 계약 요약(이슈 #64):
api.auth.user(auth:sanctum, 필수) ↔api.user.auth.user(optional.sanctum, 선택). 프론트data_source의auth_required: true는 전자에,auth_mode: "optional"은 후자에 대응한다. 어느 한쪽 미들웨어를 바꾸면 프론트 소비 계약이 침묵 속에서 깨지므로 반드시 양쪽 문서를 함께 갱신한다.