# Identity API 레퍼런스
> **소유**: 코어 · **생성**: `php artisan api:docgen` (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
---
## TL;DR (5초 요약)
```text
1. 이 문서는 실제 API 호출로 실측한 Identity 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
```
---
### GET /api/admin/identity/logs
- **라우트명**: `api.admin.identity.logs.index`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityLogController@index`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.logs.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| provider_id | query | string | 아니오 | max 64 | provider 식별자 |
| purpose | query | string | 아니오 | max 64 | 인증 목적 필터 (signup/password_reset/self_update/sensitive_action/login 또는 모듈 정의 목적) |
| status | query | string | 아니오 | — | 상태 필터 (해당 상태의 항목만 조회) |
| channel | query | string | 아니오 | max 16 | 전송 채널 필터 (email 등 — 해당 채널로 시도한 이력만) |
| origin_type | query | string | 아니오 | — | 인증 트리거 출처 유형 필터 (route/hook/policy/middleware/api/custom/system — IdentityOriginType) |
| source_type | query | string | 아니오 | — | 정책 출처 필터 (core/module/plugin/admin — 어느 확장이 인증을 요구했는지, IdentityPolicySourceType) |
| source_identifier | query | string | 아니오 | max 100 | 출처 식별자 |
| provider_ids | query | array | 아니오 | — | provider 식별자 배열 |
| purposes | query | array | 아니오 | — | 인증 목적 다중선택 필터 (여러 목적 중 하나라도 일치) |
| statuses | query | array | 아니오 | — | 상태 다중선택 필터 (여러 상태 중 하나라도 일치) |
| channels | query | array | 아니오 | — | 전송 채널 다중선택 필터 (여러 채널 중 하나라도 일치) |
| origin_types | query | array | 아니오 | — | 출처 유형 다중선택 필터 (여러 origin_type 중 하나라도 일치) |
| user_id | query | integer | 아니오 | min 1 | user 식별자 |
| target_hash | query | string | 아니오 | — | 인증 대상 해시 필터 (SHA256(email\|phone), PII 원본 대신 해시로 추적) |
| search | query | string | 아니오 | max 64 | 검색어 (지정한 검색 대상 필드에서 부분 일치) |
| search_type | query | string | 아니오 | `auto`, `user_id`, `target_hash`, `ip_address`, `policy_key` | 검색 유형 (검색 대상/방식 구분) |
| sort_by | query | string | 아니오 | `created_at`, `attempts` | 정렬 기준 필드명 |
| sort_order | query | string | 아니오 | `asc`, `desc` | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| date_from | query | date | 아니오 | — | 조회 기간 시작일 |
| date_to | query | date | 아니오 | — | 조회 기간 종료일 |
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
**요청 예시**
```http
GET /api/admin/identity/logs?provider_id=%EC%98%88%EC%8B%9C%EA%B0%92&purpose=%EC%98%88%EC%8B%9C%EA%B0%92&status=%EC%98%88%EC%8B%9C%EA%B0%92&channel=%EC%98%88%EC%8B%9C%EA%B0%92&origin_type=%EC%98%88%EC%8B%9C%EA%B0%92&source_type=%EC%98%88%EC%8B%9C%EA%B0%92&source_identifier=example-key&provider_ids=%EC%98%88%EC%8B%9C%EA%B0%92&purposes=%EC%98%88%EC%8B%9C%EA%B0%92&statuses=%EC%98%88%EC%8B%9C%EA%B0%92&channels=%EC%98%88%EC%8B%9C%EA%B0%92&origin_types=%EC%98%88%EC%8B%9C%EA%B0%92&user_id=1&target_hash=%EC%98%88%EC%8B%9C%EA%B0%92&search=%EC%98%88%EC%8B%9C%EA%B0%92&search_type=auto&sort_by=created_at&sort_order=asc&date_from=2026-01-01&date_to=2026-01-01&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_목록 응답: `data.data[]` 배열 항목의 필드 + `data.pagination`._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | string | `06f077b4-fc53-4dad-81ff-846cd6426a0f` | 기본 키 (내부 식별자) |
| provider_id | string | `inicis` | provider 식별자 (연관 리소스 참조) |
| purpose | string | `checkout_verification` | 인증 목적 (signup/password_reset/self_update/sensitive_action/login 또는 모듈 정의 목적) |
| channel | string | `email` | 인증에 사용된 전송 채널 (email 등 코어 채널 또는 모듈 provider 자체 식별자) |
| user_id | integer | `1209` | user 식별자 (연관 리소스 참조) |
| target_hash | string | `eebbbc80cbc838162aaa9437c7aba415dc81d…` | 인증 대상 해시 (SHA256(email\|phone) — PII 원본 저장 회피) |
| status | string | `verified` | 인증 시도 결과 상태 (requested/sent/processing/verified/failed/expired/cancelled/policy_violation_logged) |
| attempts | integer | `2` | 현재까지 누적된 검증 시도 횟수 |
| max_attempts | integer | `5` | 허용되는 최대 검증 시도 횟수 (초과 시 실패 처리) |
| ip_address | string | `59.16.7.205` | 요청/행위가 발생한 IP 주소 |
| user_agent | string | `Mozilla/5.0 (Windows NT 10.0; Win64; …` | 요청 클라이언트의 User-Agent 문자열 |
| origin_type | string | `policy` | 인증 트리거 출처 유형 (route/hook/policy/middleware/api/custom/system — IdentityOriginType) |
| origin_identifier | string | `sirsoft-ecommerce` | 실제 트리거 경로/훅명 (예: PUT /api/me/password, core.user.before_update) |
| origin_policy_key | string | `sirsoft-ecommerce.checkout.before_pay` | 정책이 인증을 강제한 경우 해당 identity_policies.key (정책 외 트리거는 null) |
| properties | object | `{"code_length":6}` | 요청 페이로드 요약 (감사용 부가 정보, 없으면 null) |
| metadata | object | `{"hint_used":"text_code"}` | 프로바이더 내부 데이터 (코드 해시·외부 인증 식별자 등, PII 원본 미포함) |
| created_at | string | `2026-07-30 21:14:43` | 생성 일시 |
| verified_at | string | `2026-07-30 21:21:16` | verified 일시 |
| expires_at | string | `2026-07-30 21:29:43` | expires 일시 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": {
"data": [
{
"id": "06f077b4-fc53-4dad-81ff-846cd6426a0f",
"provider_id": "inicis",
"purpose": "checkout_verification",
"channel": "email",
"user_id": null,
"target_hash": "eebbbc80cbc838162aaa9437c7aba415dc81d33a7c2c8ad21ef11e102d8ac16b",
"status": "verified",
"attempts": 2,
"max_attempts": 5,
"ip_address": "59.16.7.205",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0",
"origin_type": "policy",
"origin_identifier": "sirsoft-ecommerce",
"origin_policy_key": "sirsoft-ecommerce.checkout.before_pay",
"properties": {
"code_length": 6
},
"metadata": {
"hint_used": "text_code"
},
"created_at": "2026-07-30 21:14:43",
"verified_at": "2026-07-30 21:21:16",
"expires_at": "2026-07-30 21:29:43"
},
{
"id": "2cd9f0a8-44da-447b-96b9-81fe2174016f",
"provider_id": "g7:core.mail",
"purpose": "checkout_verification",
"channel": "email",
"user_id": null,
"target_hash": "08f2668d172fd18e4103d0e13de6159b3f7112f4c427918104af923c6c086790",
"status": "verified",
"attempts": 3,
"max_attempts": 5,
"ip_address": "180.182.50.7",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
"origin_type": "policy",
"origin_identifier": "sirsoft-ecommerce",
"origin_policy_key": "sirsoft-ecommerce.checkout.before_pay",
"properties": {
"code_length": 6
},
"metadata": {
"hint_used": "text_code"
},
"created_at": "2026-07-30 16:58:29",
"verified_at": "2026-07-30 16:59:06",
"expires_at": "2026-07-30 17:13:29"
},
"... (총 25건 중 2건 표시)"
],
"pagination": {
"current_page": 1,
"last_page": 8,
"per_page": 25,
"total": 200,
"from": 1,
"to": 25,
"has_more_pages": true
},
"abilities": {
"can_purge": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.logs.read`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 본인인증 시도 이력(성공/실패/취소/정책위반)을 관리자 화면에서 필터·검색·정렬하여 페이지네이션 조회합니다. `auth:sanctum` + `core.admin.identity.logs.read` 관리자 권한이 필요합니다. `IdentityLogService::search` 로 프로바이더·목적·상태·채널·기간 등 다중 필터를 적용하며, 응답의 `abilities.can_purge` 로 파기 권한 보유 여부를 함께 내려 UI 버튼 노출을 제어합니다. 관리자 IDV 이력 대시보드에서 특정 사용자(`user_id`)나 대상 해시(`target_hash`)로 감사 추적할 때 사용합니다.
### POST /api/admin/identity/logs/purge
- **라우트명**: `api.admin.identity.logs.purge`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityLogController@purge`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.logs.purge`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| older_than_days | body | integer | 아니오 | min 1, max 3650 | 파기 기준 보관일수 (지정 일수보다 오래된 이력만 삭제, 미지정 시 기본 180일) |
**요청 예시**
```http
POST /api/admin/identity/logs/purge HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"older_than_days": 1
}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| purged_count | integer | `200` | purged 개수 (집계) |
| older_than_days | integer | `1` | 기준 경과 일수 (이 일수보다 오래된 대상 필터/집계) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": {
"purged_count": 200,
"older_than_days": 1
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.logs.purge`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 지정한 보관주기(`older_than_days`, 기본 180일) 를 경과한 본인인증 이력을 일괄 삭제하고 삭제된 행 수를 반환합니다. `auth:sanctum` + `core.admin.identity.logs.purge` 관리자 권한이 필요합니다. `IdentityLogService::purge` 가 실제 삭제를 수행하며 되돌릴 수 없으므로, 개인정보 보관기간 정책 준수를 위해 오래된 인증 시도 로그를 정리할 때 사용합니다.
### GET /api/admin/identity/messages/definitions
- **라우트명**: `api.admin.identity.messages.definitions.index`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@index`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| search | query | string | 아니오 | max 255 | 검색어 (지정한 검색 대상 필드에서 부분 일치) |
| provider_id | query | string | 아니오 | max 64 | provider 식별자 |
| scope_type | query | string | 아니오 | — | 메시지 정의 스코프 필터 (provider_default/purpose/policy — 어느 계층 템플릿인지, IdentityMessageScopeType) |
| scope_value | query | string | 아니오 | max 120 | 스코프 값 필터 (provider_default 빈값 / purpose 키 / policy 키) |
| extension_type | query | string | 아니오 | — | 확장 유형 (core/module/plugin/template) |
| extension_identifier | query | string | 아니오 | max 100 | 확장 식별자 |
| channel | query | string | 아니오 | max 20 | 메시지 채널 필터 (mail 등 — 해당 채널 템플릿을 가진 정의만) |
| is_active | query | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
| sort_by | query | string | 아니오 | — | 정렬 기준 필드명 |
| sort_order | query | string | 아니오 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity.message_definition.index_validation_rules`).
**요청 예시**
```http
GET /api/admin/identity/messages/definitions?search=%EC%98%88%EC%8B%9C%EA%B0%92&provider_id=%EC%98%88%EC%8B%9C%EA%B0%92&scope_type=%EC%98%88%EC%8B%9C%EA%B0%92&scope_value=%EC%98%88%EC%8B%9C%EA%B0%92&extension_type=%EC%98%88%EC%8B%9C%EA%B0%92&extension_identifier=example-key&channel=%EC%98%88%EC%8B%9C%EA%B0%92&is_active=1&per_page=1&sort_by=%EC%98%88%EC%8B%9C%EA%B0%92&sort_order=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_목록 응답: `data.data[]` 배열 항목의 필드 + `data.pagination`._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| number | integer | `1` | 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
| id | integer | `1` | 기본 키 (내부 식별자) |
| provider_id | string | `g7:core.mail` | provider 식별자 (연관 리소스 참조) |
| scope_type | string | `purpose` | 메시지 정의 스코프 (provider_default: 프로바이더 기본 / purpose: 목적별 / policy: 정책별 — IdentityMessageScopeType) |
| scope_value | string | `checkout_verification` | 스코프 값 (provider_default 빈 문자열 / purpose 목적 키 / policy 정책 키) |
| name | object | `{"ko":"결제 시 본인 확인","en":"Checkout Verification"}` | 대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| description | object | `{"ko":"결제 진행 전 본인\/성인 확인 인증 코드 메일","en":"Identity\/adult …` | 설명 (다국어 필드는 로케일별 값 객체) |
| channels | array | `["mail"]` | 이 정의가 지원하는 활성 채널 목록 (현재 mail, 향후 sms 등 확장) |
| variables | array | `[{"key":"code","description":"인증 코드 (text_code 흐름)"},{"ke…` | 템플릿에서 치환 가능한 변수 메타데이터 목록 (원소 key/description) |
| extension_type | string | `module` | 이 리소스를 소유한 확장의 타입 (core/module/plugin/template) |
| extension_identifier | string | `sirsoft-ecommerce` | 이 리소스를 소유한 확장의 식별자 |
| is_active | boolean | `true` | active 여부 |
| is_default | boolean | `true` | default 여부 |
| user_overrides | array | `["name.ja"]` | 운영자가 시드 기본값에서 수정한 필드 경로 목록 (예: name.ja — 시더 재실행 시 보존 대상) |
| templates | array | `[{"id":1,"definition_id":1,"channel":"mail","subject":{"k…` | 이 정의에 속한 채널별 하위 메시지 템플릿 목록 (원소 id/channel/subject/body 등). **목록 조회에서는 대표 1건만 실린다** — 전체 채널이 필요하면 단건 조회를 사용한다 |
| templates_count | integer | `1` | templates 개수 (집계) |
| created_at | string | `2026-07-30 18:47:09` | 생성 일시 |
| updated_at | string | `2026-07-30 18:47:09` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":false}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "IDV 메시지 정의 목록을 조회했습니다.",
"data": {
"data": [
{
"number": 1,
"id": 1,
"provider_id": "g7:core.mail",
"scope_type": "purpose",
"scope_value": "checkout_verification",
"...": "(14개 키 생략, 총 19개)"
},
{
"number": 2,
"id": 2,
"provider_id": "g7:core.mail",
"scope_type": "provider_default",
"scope_value": "",
"...": "(14개 키 생략, 총 19개)"
},
"... (총 6건 중 2건 표시)"
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 25,
"total": 6,
"from": 1,
"...": "(2개 키 생략, 총 7개)"
},
"abilities": {
"can_create": true,
"can_update": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.read`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 본인인증 알림 메시지 정의(프로바이더별·목적별·정책별 메일/SMS 템플릿 묶음) 목록을 필터·검색하여 페이지네이션 조회합니다. `auth:sanctum` + `core.admin.identity.messages.read` 관리자 권한이 필요합니다. 확장이 `core.identity.message_definition.index_validation_rules` 필터 훅으로 추가 검색 파라미터를 등록할 수 있습니다. 응답 각 항목의 `user_overrides` 로 운영자가 시드 기본값에서 수정한 필드를 함께 내려 관리자 메시지 설정 화면을 구성할 때 사용합니다. 목록의 `templates` 에는 **대표 템플릿 1건만** 실리고, 전체 채널 수는 `templates_count` 로 제공합니다 — 정의마다 채널×로케일 템플릿 본문을 전부 실으면 목록을 여는 것만으로 전 행의 메일 본문이 전송되기 때문입니다. 채널별 템플릿 전체가 필요하면 단건 조회(`GET /api/admin/identity/messages/definitions/{definition}`)를 사용합니다.
### POST /api/admin/identity/messages/definitions
- **라우트명**: `api.admin.identity.messages.definitions.store`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@store`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| provider_id | body | string | 예 | max 64 | provider 식별자 |
| scope_type | body | string | 예 | — | 메시지 정의 스코프 (관리자 생성은 policy 만 허용 — provider_default/purpose 는 시드 영역) |
| scope_value | body | string | 예 | max 120 | 스코프 값 (source_type='admin' 인 IdentityPolicy.key 와 일치해야 함) |
| name | body | array | 예 | — | 대상의 이름/명칭 |
| description | body | array | 아니오 | — | 설명 |
| channels | body | array | 예 | min 1 | 지원 채널 목록 (최소 1개, 현재 mail 만 허용) |
| variables | body | array | 아니오 | — | 템플릿 치환 변수 메타데이터 목록 (원소 key/description, key 는 영문 식별자) |
| templates | body | array | 예 | min 1 | 채널별 하위 템플릿 배열 (최소 1개, 원소 channel/subject/body 다국어 배열) |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity.message_definition.store_validation_rules`).
**요청 예시**
```http
POST /api/admin/identity/messages/definitions HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"provider_id": "예시값",
"scope_type": "예시값",
"scope_value": "예시값",
"name": [
"예시 이름"
],
"description": [
"예시 내용입니다."
],
"channels": [
"예시값"
],
"variables": [
"예시값"
],
"templates": [
"예시값"
]
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 운영자가 정책(policy) 매핑용 메시지 정의를 신규 생성합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. `IdentityMessageDefinitionService::createAdminDefinition` 이 처리하며 `scope_type='policy'` + `scope_value` 가 admin policy.key 와 매칭되는 경우만 허용됩니다(FormRequest 검증). `channels`·`templates` 를 최소 1개 이상 포함해야 하며, 확장은 `core.identity.message_definition.store_validation_rules` 필터 훅으로 검증 규칙을 확장할 수 있습니다. 특정 인증 정책에 전용 메일/SMS 문구를 붙이고자 할 때 사용하며 성공 시 201 로 응답합니다.
### DELETE /api/admin/identity/messages/definitions/{definition}
- **라우트명**: `api.admin.identity.messages.definitions.destroy`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@destroy`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| definition | path | string | 예 | — | 대상 definition의 식별자 |
**요청 예시**
```http
DELETE /api/admin/identity/messages/definitions/1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 운영자가 추가한 메시지 정의를 삭제합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. 시드로 제공되는 `is_default=true` 정의는 삭제가 거부되어 403 을 반환하며(선언형 보호), 삭제 시 FK cascade 로 자식 템플릿이 함께 제거됩니다. 잘못 만들었거나 더 이상 쓰지 않는 정책 전용 메시지 정의를 정리할 때 사용합니다.
### GET /api/admin/identity/messages/definitions/{definition}
- **라우트명**: `api.admin.identity.messages.definitions.show`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@show`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| definition | path | string | 예 | — | 대상 definition의 식별자 |
**요청 예시**
```http
GET /api/admin/identity/messages/definitions/1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `1` | 기본 키 (내부 식별자) |
| provider_id | string | `g7:core.mail` | IDV 프로바이더 ID (예: g7:core.mail, kcp, portone) |
| scope_type | string | `purpose` | 메시지 정의 스코프 (provider_default\|purpose\|policy) — App\Enums\IdentityMessageScopeType enum |
| scope_value | string | `checkout_verification` | 범위 값: provider_default 빈 문자열 / purpose 키 / policy 키 |
| name | object | `{"ko":"결제 시 본인 확인","en":"Checkout Verification"}` | 다국어 표시명 ({"ko":"...", "en":"..."}) |
| description | object | `{"ko":"결제 진행 전 본인\/성인 확인 인증 코드 메일","en":"Identity\/adult …` | 다국어 설명 |
| channels | array | `["mail"]` | 활성 채널 (현재 ["mail"], 향후 sms 등 확장) |
| variables | array | `[{"key":"code","description":"인증 코드 (text_code 흐름)"},{"ke…` | 사용 가능 변수 메타데이터 ([{key, description}]) |
| extension_type | string | `module` | 확장 타입: core, module, plugin |
| extension_identifier | string | `sirsoft-ecommerce` | 확장 식별자 |
| is_active | boolean | `true` | active 여부 |
| is_default | boolean | `true` | default 여부 |
| user_overrides | null | `null` | 운영자가 수정한 필드명 목록 (예: ["name","is_active"]) |
| templates | array | `[{"id":1,"definition_id":1,"channel":"mail","subject":{"k…` | 이 정의에 속한 채널별 하위 메시지 템플릿 목록 (원소 id/channel/subject/body 등) |
| created_at | string | `2026-07-30 18:47:09` | 생성 일시 |
| updated_at | string | `2026-07-30 18:47:09` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":false}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "IDV 메시지 정의 상세를 조회했습니다.",
"data": {
"id": 1,
"provider_id": "g7:core.mail",
"scope_type": "purpose",
"scope_value": "checkout_verification",
"name": {
"ko": "결제 시 본인 확인",
"en": "Checkout Verification"
},
"description": {
"ko": "결제 진행 전 본인/성인 확인 인증 코드 메일",
"en": "Identity/adult verification code mail before checkout"
},
"channels": [
"mail"
],
"variables": [
{
"key": "code",
"description": "인증 코드 (text_code 흐름)"
},
{
"key": "expire_minutes",
"description": "만료까지 남은 분"
},
{
"key": "purpose_label",
"description": "인증 목적 라벨"
},
{
"key": "app_name",
"description": "사이트명"
},
{
"key": "site_url",
"description": "사이트 URL"
},
{
"key": "recipient_email",
"description": "수신자 이메일"
}
],
"extension_type": "module",
"extension_identifier": "sirsoft-ecommerce",
"is_active": true,
"is_default": true,
"user_overrides": null,
"templates": [
{
"id": 1,
"definition_id": 1,
"channel": "mail",
"subject": {
"ko": "[{app_name}] 결제 본인 확인 인증 코드",
"en": "[{app_name}] Checkout Verification Code"
},
"body": {
"ko": "결제 본인 확인
결제를 진행하기 위해 본인 확인이 필요합니다. 아래 인증 코드를 입력해 주세요.
{code}
이 코드는 {expire_minutes}분 후 만료됩니다.
본인이 결제를 진행하지 않았다면 이 메일을 무시하고 즉시 비밀번호를 변경해 주세요.
감사합니다,
{app_name}
",
"en": "Checkout Verification
Please enter the code below to proceed with payment.
{code}
This code will expire in {expire_minutes} minutes.
If you did not initiate this payment, please ignore this email and change your password immediately.
Thank you,
{app_name}
"
},
"is_active": true,
"is_default": true,
"user_overrides": null,
"updated_by": null,
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-07-30 18:47:09",
"abilities": {
"can_update": true,
"can_delete": true
}
}
],
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-07-30 18:47:09",
"abilities": {
"can_update": true,
"can_delete": false
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.read`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 단일 메시지 정의의 상세 정보를 조회합니다(하위 채널 템플릿 eager load 포함). `auth:sanctum` + `core.admin.identity.messages.read` 관리자 권한이 필요합니다. 관리자 편집 모달을 열 때 해당 정의의 다국어 이름/설명·활성 채널·사용 가능 변수·`user_overrides`·`templates` 전체를 로드하기 위해 사용합니다.
### PATCH /api/admin/identity/messages/definitions/{definition}
- **라우트명**: `api.admin.identity.messages.definitions.update`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@update`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| definition | path | string | 예 | — | 대상 definition의 식별자 |
| name | body | array | 아니오 | — | 대상의 이름/명칭 |
| description | body | array | 아니오 | — | 설명 |
| channels | body | array | 아니오 | min 1 | 지원 채널 목록 (최소 1개 — 이 정의가 발송할 채널 조정) |
| is_active | body | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity.message_definition.update_validation_rules`).
**요청 예시**
```http
PATCH /api/admin/identity/messages/definitions/1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"name": [
"예시 이름"
],
"description": [
"예시 내용입니다."
],
"channels": [
"예시값"
],
"is_active": true
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 메시지 정의의 편집 가능 속성(`name`, `description`, `channels`, `is_active`) 을 수정합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. `IdentityMessageDefinitionService::updateDefinition` 이 처리하며 수정된 필드는 `user_overrides` 에 기록되어 시더 재실행 시에도 보존됩니다. 확장은 `core.identity.message_definition.update_validation_rules` 필터 훅으로 검증 규칙을 확장할 수 있습니다. 시드 정의의 표시명이나 활성 채널을 운영 상황에 맞게 조정할 때 사용합니다.
### POST /api/admin/identity/messages/definitions/{definition}/reset
- **라우트명**: `api.admin.identity.messages.definitions.reset`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@reset`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| definition | path | string | 예 | — | 대상 definition의 식별자 |
**요청 예시**
```http
POST /api/admin/identity/messages/definitions/1/reset HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `1` | 기본 키 (내부 식별자) |
| provider_id | string | `g7:core.mail` | provider 식별자 (연관 리소스 참조) |
| scope_type | string | `purpose` | 메시지 정의 스코프 (provider_default\|purpose\|policy) — App\Enums\IdentityMessageScopeType enum |
| scope_value | string | `checkout_verification` | 범위 값: provider_default 빈 문자열 / purpose 키 / policy 키 |
| name | object | `{"ko":"결제 시 본인 확인","en":"Checkout Verification"}` | 대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| description | object | `{"ko":"결제 진행 전 본인\/성인 확인 인증 코드 메일","en":"Identity\/adult …` | 설명 (다국어 필드는 로케일별 값 객체) |
| channels | array | `["mail"]` | 활성 채널 (현재 ["mail"], 향후 sms 등 확장) |
| variables | array | `[{"key":"code","description":"인증 코드 (text_code 흐름)"},{"ke…` | 사용 가능 변수 메타데이터 ([{key, description}]) |
| extension_type | string | `module` | 이 리소스를 소유한 확장의 타입 (core/module/plugin/template) |
| extension_identifier | string | `sirsoft-ecommerce` | 이 리소스를 소유한 확장의 식별자 |
| is_active | boolean | `true` | active 여부 |
| is_default | boolean | `true` | default 여부 |
| user_overrides | null | `null` | 운영자가 수정한 필드명 목록 (예: ["name","is_active"]) |
| templates | array | `[{"id":1,"definition_id":1,"channel":"mail","subject":{"k…` | 템플릿 목록 (각 원소 identifier/name 등 — 템플릿 관계 파생) |
| created_at | string | `2026-07-30 18:47:09` | 생성 일시 |
| updated_at | string | `2026-07-30 18:47:09` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":false}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "IDV 메시지 정의가 기본값으로 복원되었습니다.",
"data": {
"id": 1,
"provider_id": "g7:core.mail",
"scope_type": "purpose",
"scope_value": "checkout_verification",
"name": {
"ko": "결제 시 본인 확인",
"en": "Checkout Verification"
},
"description": {
"ko": "결제 진행 전 본인/성인 확인 인증 코드 메일",
"en": "Identity/adult verification code mail before checkout"
},
"channels": [
"mail"
],
"variables": [
{
"key": "code",
"description": "인증 코드 (text_code 흐름)"
},
{
"key": "expire_minutes",
"description": "만료까지 남은 분"
},
{
"key": "purpose_label",
"description": "인증 목적 라벨"
},
{
"key": "app_name",
"description": "사이트명"
},
{
"key": "site_url",
"description": "사이트 URL"
},
{
"key": "recipient_email",
"description": "수신자 이메일"
}
],
"extension_type": "module",
"extension_identifier": "sirsoft-ecommerce",
"is_active": true,
"is_default": true,
"user_overrides": null,
"templates": [
{
"id": 1,
"definition_id": 1,
"channel": "mail",
"subject": {
"ko": "[{app_name}] 결제 본인 확인 인증 코드",
"en": "[{app_name}] Checkout Verification Code"
},
"body": {
"ko": "결제 본인 확인
결제를 진행하기 위해 본인 확인이 필요합니다. 아래 인증 코드를 입력해 주세요.
{code}
이 코드는 {expire_minutes}분 후 만료됩니다.
본인이 결제를 진행하지 않았다면 이 메일을 무시하고 즉시 비밀번호를 변경해 주세요.
감사합니다,
{app_name}
",
"en": "Checkout Verification
Please enter the code below to proceed with payment.
{code}
This code will expire in {expire_minutes} minutes.
If you did not initiate this payment, please ignore this email and change your password immediately.
Thank you,
{app_name}
"
},
"is_active": true,
"is_default": true,
"user_overrides": null,
"updated_by": null,
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-07-30 18:47:09",
"abilities": {
"can_update": true,
"can_delete": true
}
}
],
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-07-30 18:47:09",
"abilities": {
"can_update": true,
"can_delete": false
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 메시지 정의에 속한 모든 채널 템플릿을 시더 기본값으로 일괄 복원하고 정의를 default 상태로 되돌립니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. 각 하위 템플릿에 대해 `IdentityMessageTemplateService::resetToDefault` 를 호출한 뒤 `markAsDefault` 로 정의를 표시하므로, 운영자가 수정한 문구를 한 번에 원상복구할 때 사용합니다.
### PATCH /api/admin/identity/messages/definitions/{definition}/toggle-active
- **라우트명**: `api.admin.identity.messages.definitions.toggle-active`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageDefinitionController@toggleActive`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| definition | path | string | 예 | — | 대상 definition의 식별자 |
**요청 예시**
```http
PATCH /api/admin/identity/messages/definitions/1/toggle-active HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `1` | 기본 키 (내부 식별자) |
| provider_id | string | `g7:core.mail` | provider 식별자 (연관 리소스 참조) |
| scope_type | string | `purpose` | 메시지 정의 스코프 (provider_default\|purpose\|policy) — App\Enums\IdentityMessageScopeType enum |
| scope_value | string | `checkout_verification` | 범위 값: provider_default 빈 문자열 / purpose 키 / policy 키 |
| name | object | `{"ko":"결제 시 본인 확인","en":"Checkout Verification"}` | 대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| description | object | `{"ko":"결제 진행 전 본인\/성인 확인 인증 코드 메일","en":"Identity\/adult …` | 설명 (다국어 필드는 로케일별 값 객체) |
| channels | array | `["mail"]` | 활성 채널 (현재 ["mail"], 향후 sms 등 확장) |
| variables | array | `[{"key":"code","description":"인증 코드 (text_code 흐름)"},{"ke…` | 사용 가능 변수 메타데이터 ([{key, description}]) |
| extension_type | string | `module` | 이 리소스를 소유한 확장의 타입 (core/module/plugin/template) |
| extension_identifier | string | `sirsoft-ecommerce` | 이 리소스를 소유한 확장의 식별자 |
| is_active | boolean | `false` | active 여부 |
| is_default | boolean | `true` | default 여부 |
| user_overrides | array | `["is_active"]` | 운영자가 수정한 필드명 목록 (예: ["name","is_active"]) |
| created_at | string | `2026-07-30 18:47:09` | 생성 일시 |
| updated_at | string | `2026-08-04 21:53:38` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":false}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "IDV 메시지 정의 활성 상태가 변경되었습니다.",
"data": {
"id": 1,
"provider_id": "g7:core.mail",
"scope_type": "purpose",
"scope_value": "checkout_verification",
"name": {
"ko": "결제 시 본인 확인",
"en": "Checkout Verification"
},
"description": {
"ko": "결제 진행 전 본인/성인 확인 인증 코드 메일",
"en": "Identity/adult verification code mail before checkout"
},
"channels": [
"mail"
],
"variables": [
{
"key": "code",
"description": "인증 코드 (text_code 흐름)"
},
{
"key": "expire_minutes",
"description": "만료까지 남은 분"
},
{
"key": "purpose_label",
"description": "인증 목적 라벨"
},
{
"key": "app_name",
"description": "사이트명"
},
{
"key": "site_url",
"description": "사이트 URL"
},
{
"key": "recipient_email",
"description": "수신자 이메일"
}
],
"extension_type": "module",
"extension_identifier": "sirsoft-ecommerce",
"is_active": false,
"is_default": true,
"user_overrides": [
"is_active"
],
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-08-04 21:53:38",
"abilities": {
"can_update": true,
"can_delete": false
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 메시지 정의의 활성/비활성 상태를 토글합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. `IdentityMessageDefinitionService::toggleActive` 가 현재 `is_active` 값을 반전시키며, 특정 목적/정책용 인증 메시지 발송을 임시로 끄거나 다시 켤 때 사용합니다.
### POST /api/admin/identity/messages/templates/preview
- **라우트명**: `api.admin.identity.messages.templates.preview`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageTemplateController@preview`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| template_id | body | integer | 예 | — | template 식별자 |
| data | body | array | 아니오 | — | 데이터 페이로드 |
| locale | body | string | 아니오 | max 10 | 로케일 코드 (표시 언어/지역) |
**요청 예시**
```http
POST /api/admin/identity/messages/templates/preview HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"template_id": 1,
"data": [
"예시값"
],
"locale": "ko"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.read`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 지정한 템플릿(`template_id`) 의 제목/본문에 변수(`data`) 를 치환한 결과를 지정 로케일(`locale`) 로 렌더링해 미리보기를 반환합니다. `auth:sanctum` + `core.admin.identity.messages.read` 관리자 권한이 필요합니다. `IdentityMessageTemplateService::getPreview` 가 실제 발송 없이 렌더 결과만 생성하므로, 운영자가 편집한 문구가 실제 메일/SMS 에서 어떻게 보일지 저장 전에 확인할 때 사용합니다.
### PATCH /api/admin/identity/messages/templates/{template}
- **라우트명**: `api.admin.identity.messages.templates.update`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageTemplateController@update`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| template | path | string | 예 | — | 대상 template의 식별자 |
| subject | body | array | 아니오 | — | 제목 |
| body | body | array | 예 | — | 본문 |
| is_active | body | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity.message_template.update_validation_rules`).
**요청 예시**
```http
PATCH /api/admin/identity/messages/templates/1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"subject": [
"예시값"
],
"body": [
"예시값"
],
"is_active": true
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 개별 채널 메시지 템플릿의 제목(`subject`)·본문(`body`)·활성 여부(`is_active`) 를 수정합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. `body` 는 필수이며 다국어 배열로 전달합니다. `IdentityMessageTemplateService::updateTemplate` 이 처리하고 확장은 `core.identity.message_template.update_validation_rules` 필터 훅으로 검증을 확장할 수 있습니다. 인증 메일/SMS 의 실제 발송 문구를 편집할 때 사용합니다.
### POST /api/admin/identity/messages/templates/{template}/reset
- **라우트명**: `api.admin.identity.messages.templates.reset`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageTemplateController@reset`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| template | path | string | 예 | — | 대상 template의 식별자 |
**요청 예시**
```http
POST /api/admin/identity/messages/templates/1/reset HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `1` | 기본 키 (내부 식별자) |
| definition_id | integer | `1` | definition 식별자 (연관 리소스 참조) |
| channel | string | `mail` | 메시지 템플릿 채널 (mail 현재 / sms 등 향후) — IdentityVerificationChannel 과는 별개의 도메인 분류 |
| subject | object | `{"ko":"[{app_name}] 결제 본인 확인 인증 코드","en":"[{app_name}] Ch…` | 다국어 제목 ({"ko":"...", "en":"..."}) — mail 채널에서만 의미 |
| body | object | `{"ko":"결제 본인 확인<\/h1>
결제를 진행하기 위해 본인 확인이 필요합니다. 아래 …` | 다국어 본문 ({"ko":"...", "en":"..."}) |
| is_active | boolean | `true` | active 여부 |
| is_default | boolean | `true` | default 여부 |
| user_overrides | null | `null` | 운영자가 수정한 필드명 목록 (예: ["subject","body","is_active"]) |
| updated_by | null | `null` | 최종 수정한 사용자 정보 (uuid/name — updated_by 관계 파생, 없으면 null) |
| created_at | string | `2026-07-30 18:47:09` | 생성 일시 |
| updated_at | string | `2026-07-30 18:47:09` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "IDV 메시지 템플릿이 기본값으로 복원되었습니다.",
"data": {
"id": 1,
"definition_id": 1,
"channel": "mail",
"subject": {
"ko": "[{app_name}] 결제 본인 확인 인증 코드",
"en": "[{app_name}] Checkout Verification Code"
},
"body": {
"ko": "
결제 본인 확인
결제를 진행하기 위해 본인 확인이 필요합니다. 아래 인증 코드를 입력해 주세요.
{code}
이 코드는 {expire_minutes}분 후 만료됩니다.
본인이 결제를 진행하지 않았다면 이 메일을 무시하고 즉시 비밀번호를 변경해 주세요.
감사합니다,
{app_name}
",
"en": "Checkout Verification
Please enter the code below to proceed with payment.
{code}
This code will expire in {expire_minutes} minutes.
If you did not initiate this payment, please ignore this email and change your password immediately.
Thank you,
{app_name}
"
},
"is_active": true,
"is_default": true,
"user_overrides": null,
"updated_by": null,
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-07-30 18:47:09",
"abilities": {
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 개별 메시지 템플릿을 시더 기본값으로 복원합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. `IdentityMessageTemplateService::resetToDefault` 가 운영자 수정 내용을 폐기하고 최초 제공 문구로 되돌리므로, 특정 채널 템플릿 하나만 원상복구할 때 사용합니다(정의 전체 복원은 definition reset 사용).
### PATCH /api/admin/identity/messages/templates/{template}/toggle-active
- **라우트명**: `api.admin.identity.messages.templates.toggle-active`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityMessageTemplateController@toggleActive`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.messages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| template | path | string | 예 | — | 대상 template의 식별자 |
**요청 예시**
```http
PATCH /api/admin/identity/messages/templates/1/toggle-active HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `1` | 기본 키 (내부 식별자) |
| definition_id | integer | `1` | definition 식별자 (연관 리소스 참조) |
| channel | string | `mail` | 메시지 템플릿 채널 (mail 현재 / sms 등 향후) — IdentityVerificationChannel 과는 별개의 도메인 분류 |
| subject | object | `{"ko":"[{app_name}] 결제 본인 확인 인증 코드","en":"[{app_name}] Ch…` | 다국어 제목 ({"ko":"...", "en":"..."}) — mail 채널에서만 의미 |
| body | object | `{"ko":"결제 본인 확인<\/h1>
결제를 진행하기 위해 본인 확인이 필요합니다. 아래 …` | 다국어 본문 ({"ko":"...", "en":"..."}) |
| is_active | boolean | `false` | active 여부 |
| is_default | boolean | `true` | default 여부 |
| user_overrides | array | `["is_active"]` | 운영자가 수정한 필드명 목록 (예: ["subject","body","is_active"]) |
| updated_by | null | `null` | 최종 수정한 사용자 정보 (uuid/name — updated_by 관계 파생, 없으면 null) |
| created_at | string | `2026-07-30 18:47:09` | 생성 일시 |
| updated_at | string | `2026-08-04 21:53:39` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "IDV 메시지 템플릿 활성 상태가 변경되었습니다.",
"data": {
"id": 1,
"definition_id": 1,
"channel": "mail",
"subject": {
"ko": "[{app_name}] 결제 본인 확인 인증 코드",
"en": "[{app_name}] Checkout Verification Code"
},
"body": {
"ko": "
결제 본인 확인
결제를 진행하기 위해 본인 확인이 필요합니다. 아래 인증 코드를 입력해 주세요.
{code}
이 코드는 {expire_minutes}분 후 만료됩니다.
본인이 결제를 진행하지 않았다면 이 메일을 무시하고 즉시 비밀번호를 변경해 주세요.
감사합니다,
{app_name}
",
"en": "Checkout Verification
Please enter the code below to proceed with payment.
{code}
This code will expire in {expire_minutes} minutes.
If you did not initiate this payment, please ignore this email and change your password immediately.
Thank you,
{app_name}
"
},
"is_active": false,
"is_default": true,
"user_overrides": [
"is_active"
],
"updated_by": null,
"created_at": "2026-07-30 18:47:09",
"updated_at": "2026-08-04 21:53:39",
"abilities": {
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.messages.update`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 개별 메시지 템플릿의 활성/비활성 상태를 토글합니다. `auth:sanctum` + `core.admin.identity.messages.update` 관리자 권한이 필요합니다. `IdentityMessageTemplateService::toggleActive` 가 현재 `is_active` 값을 반전시키며, 특정 채널(예: 메일) 발송만 임시로 중단하거나 재개할 때 사용합니다.
### GET /api/admin/identity/policies
- **라우트명**: `api.admin.identity.policies.index`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityPolicyController@index`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.policies.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| scope | query | string | 아니오 | — | 조회 범위 한정 키 |
| purpose | query | string | 아니오 | max 64 | 인증 목적 필터 (해당 목적을 요구하는 정책만 조회) |
| source_type | query | string | 아니오 | — | 정책 출처 필터 (core/module/plugin/admin — 선언형 vs 운영자 정책 구분, IdentityPolicySourceType) |
| source_identifier | query | string | 아니오 | max 100 | 출처 식별자 |
| applies_to | query | string | 아니오 | — | 적용 대상 사용자 필터 (self: 일반 사용자 / admin: 관리자 / both: 모두, IdentityPolicyAppliesTo) |
| fail_mode | query | string | 아니오 | — | 실패 시 동작 필터 (block: 428 차단 / log_only: 감사 로그만, IdentityPolicyFailMode) |
| enabled | query | boolean | 아니오 | — | 사용 여부 |
| search | query | string | 아니오 | max 255 | 검색어 (지정한 검색 대상 필드에서 부분 일치) |
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
**요청 예시**
```http
GET /api/admin/identity/policies?scope=%EC%98%88%EC%8B%9C%EA%B0%92&purpose=%EC%98%88%EC%8B%9C%EA%B0%92&source_type=%EC%98%88%EC%8B%9C%EA%B0%92&source_identifier=example-key&applies_to=%EC%98%88%EC%8B%9C%EA%B0%92&fail_mode=%EC%98%88%EC%8B%9C%EA%B0%92&enabled=1&search=%EC%98%88%EC%8B%9C%EA%B0%92&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_목록 응답: `data.data[]` 배열 항목의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `29` | 기본 키 (내부 식별자) |
| key | string | `core.admin.extension_uninstall` | 정책 식별자 (고유, 예: core.profile.password_change) |
| scope | string | `route` | 정책 적용 범위 (route: 라우트 패턴 / hook: Service 훅 / custom: 모듈 커스텀 키, IdentityPolicyScope) |
| target | string | `api.admin.{modules,plugins}.uninstall` | 매칭 대상 (scope 에 따라 라우트명/URI 패턴, 훅 이름, 또는 custom key) |
| purpose | string | `sensitive_action` | 이 정책이 요구하는 인증 목적 |
| provider_id | null | `null` | provider 식별자 (연관 리소스 참조) |
| grace_minutes | integer | `0` | 재인증 유예 시간(분) — 최근 N분 이내 동일 목적 인증 성공 시 재인증 생략 (0=매번 요구) |
| enabled | boolean | `false` | 정책 사용 여부 (false 시 인증 미강제) |
| priority | integer | `100` | 정책 우선순위 (같은 대상에 여러 정책 매칭 시 작을수록 우선) |
| conditions | object | `{"changed_fields":["email","phone","mobile"]}` | 추가 매칭 조건 (역할/HTTP 메서드/파라미터 매칭 조건 JSON, 없으면 빈 배열) |
| source_type | string | `core` | 정책 출처 (core/module/plugin: 선언형 / admin: 운영자 직접 등록, IdentityPolicySourceType) |
| source_identifier | string | `core` | 출처 식별자 (선언형 정책의 소유 확장 identifier) |
| applies_to | string | `admin` | 적용 대상 사용자 (self: 일반 사용자 / admin: 관리자 / both: 모두, IdentityPolicyAppliesTo) |
| fail_mode | string | `block` | 실패 시 동작 (block: HTTP 428 차단 / log_only: 감사 로그만 남기고 통과, IdentityPolicyFailMode) |
| user_overrides | array | `[]` | 운영자가 선언 기본값에서 재정의한 필드 목록 (선언형 정책만 의미, 시더 재실행 시 보존) |
| created_at | string | `2026-07-31 00:15:09` | 생성 일시 |
| updated_at | string | `2026-07-31 00:15:09` | 최종 수정 일시 |
| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": {
"data": [
{
"id": 29,
"key": "core.admin.extension_uninstall",
"scope": "route",
"target": "api.admin.{modules,plugins}.uninstall",
"purpose": "sensitive_action",
"provider_id": null,
"grace_minutes": 0,
"enabled": false,
"priority": 100,
"conditions": null,
"source_type": "core",
"source_identifier": "core",
"applies_to": "admin",
"fail_mode": "block",
"user_overrides": [],
"created_at": "2026-07-31 00:15:09",
"updated_at": "2026-07-31 00:15:09",
"abilities": {
"can_update": true,
"can_delete": true
}
},
{
"id": 28,
"key": "core.admin.user_delete",
"scope": "hook",
"target": "core.user.before_delete",
"purpose": "sensitive_action",
"provider_id": null,
"grace_minutes": 0,
"enabled": false,
"priority": 100,
"conditions": null,
"source_type": "core",
"source_identifier": "core",
"applies_to": "admin",
"fail_mode": "block",
"user_overrides": [],
"created_at": "2026-07-31 00:15:09",
"updated_at": "2026-07-31 00:15:09",
"abilities": {
"can_update": true,
"can_delete": true
}
},
"... (총 21건 중 2건 표시)"
],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
},
"meta": {
"current_page": 1,
"per_page": 25,
"total": 21,
"last_page": 1
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.policies.read`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 본인인증 정책(어느 시점/위치에서 어떤 목적의 인증을 요구할지) 목록을 필터·검색하여 페이지네이션 조회합니다. `auth:sanctum` + `core.admin.identity.policies.read` 관리자 권한이 필요합니다. `IdentityPolicyService::search` 로 scope·purpose·source_type·enabled 등을 필터링하며, 응답의 `source_type` 으로 선언형(core/module/plugin) 정책과 운영자 정책(admin) 을 구분하고 `user_overrides` 로 운영자가 재정의한 필드를 표시합니다. 관리자 IDV 정책 DataGrid 를 구성할 때 사용합니다.
### POST /api/admin/identity/policies
- **라우트명**: `api.admin.identity.policies.store`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityPolicyController@store`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.policies.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| key | body | string | 예 | max 120 | 정책 식별자 (고유, 예: core.profile.password_change) |
| scope | body | string | 예 | — | 조회 범위 한정 키 |
| target | body | string | 예 | max 255 | 매칭 대상 (scope 에 따라 라우트명/URI 패턴, 훅 이름, 또는 custom key) |
| purpose | body | string | 예 | max 64 | 이 정책이 요구하는 인증 목적 |
| provider_id | body | string | 아니오 | max 64 | provider 식별자 |
| grace_minutes | body | integer | 예 | min 0, max 43200 | 재인증 유예 시간(분) — 최근 N분 이내 동일 목적 인증 성공 시 재인증 생략 (0=매번 요구) |
| enabled | body | boolean | 아니오 | — | 사용 여부 |
| priority | body | integer | 아니오 | min 0, max 65535 | 우선순위 (작을수록 우선) |
| conditions | body | array | 아니오 | — | 추가 매칭 조건 (역할/HTTP 메서드/파라미터 매칭 조건 JSON) |
| applies_to | body | string | 예 | — | 적용 대상 사용자 (self: 일반 사용자 / admin: 관리자 / both: 모두, IdentityPolicyAppliesTo) |
| fail_mode | body | string | 예 | — | 실패 시 동작 (block: HTTP 428 차단 / log_only: 감사 로그만 남기고 통과, IdentityPolicyFailMode) |
| source_identifier | body | string | 아니오 | max 100 | 출처 식별자 |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity_policy.store_validation_rules`).
**요청 예시**
```http
POST /api/admin/identity/policies HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"key": "예시값",
"scope": "예시값",
"target": "예시값",
"purpose": "예시값",
"provider_id": "예시값",
"grace_minutes": 1,
"enabled": true,
"priority": 1,
"conditions": [
"예시값"
],
"applies_to": "예시값",
"fail_mode": "예시값",
"source_identifier": "example-key"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.policies.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 운영자가 새 본인인증 정책을 생성합니다(`source_type='admin'` 고정). `auth:sanctum` + `core.admin.identity.policies.update` 관리자 권한이 필요합니다. `IdentityPolicyService::createAdminPolicy` 가 처리하며 `key`·`scope`·`target`·`purpose`·`grace_minutes`·`applies_to`·`fail_mode` 등을 지정합니다. 확장은 `core.identity_policy.store_validation_rules` 필터 훅으로 검증을 확장할 수 있습니다. 특정 라우트/훅 지점에 코어가 선언하지 않은 인증 요구를 관리자가 직접 추가할 때 사용하며 성공 시 201 로 응답합니다.
### DELETE /api/admin/identity/policies/{id}
- **라우트명**: `api.admin.identity.policies.destroy`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityPolicyController@destroy`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.policies.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| id | path | string | 예 | — | 대상 리소스의 식별자 |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity_policy.destroy_validation_rules`).
**요청 예시**
```http
DELETE /api/admin/identity/policies/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.policies.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 본인인증 정책을 삭제합니다. `auth:sanctum` + `core.admin.identity.policies.update` 관리자 권한이 필요합니다. `source_type='admin'` 인 운영자 정책만 삭제할 수 있고, 선언형 정책(core/module/plugin) 은 403 을 반환하므로 삭제 대신 비활성화(update 로 `enabled=false`) 로 대체해야 합니다. 확장은 `core.identity_policy.destroy_validation_rules` 필터 훅으로 검증을 확장할 수 있습니다. 운영자가 잘못 만든 정책을 제거할 때 사용합니다.
### PUT /api/admin/identity/policies/{id}
- **라우트명**: `api.admin.identity.policies.update`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityPolicyController@update`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.policies.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| enabled | body | boolean | 아니오 | — | 사용 여부 |
| grace_minutes | body | integer | 아니오 | min 0, max 43200 | 재인증 유예 시간(분) — 최근 N분 이내 동일 목적 인증 성공 시 재인증 생략 (0=매번 요구) |
| provider_id | body | string | 아니오 | max 64 | provider 식별자 |
| fail_mode | body | string | 아니오 | — | 실패 시 동작 (block: HTTP 428 차단 / log_only: 감사 로그만 남기고 통과, IdentityPolicyFailMode) |
| key | body | string | 아니오 | max 120 | 정책 식별자 (admin 정책만 변경 가능, 선언형 정책은 확장 지점 식별자라 변경 차단) |
| scope | body | string | 아니오 | — | 조회 범위 한정 키 |
| target | body | string | 아니오 | max 255 | 매칭 대상 (admin 정책만 변경 가능, 선언형 정책은 변경 차단) |
| purpose | body | string | 아니오 | max 64 | 이 정책이 요구하는 인증 목적 |
| priority | body | integer | 아니오 | min 0, max 65535 | 우선순위 (작을수록 우선) |
| conditions | body | array | 아니오 | — | 추가 매칭 조건 (역할/HTTP 메서드/파라미터 매칭 조건 JSON) |
| applies_to | body | string | 아니오 | — | 적용 대상 사용자 (self: 일반 사용자 / admin: 관리자 / both: 모두, IdentityPolicyAppliesTo) |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity_policy.update_validation_rules`).
**요청 예시**
```http
PUT /api/admin/identity/policies/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"enabled": true,
"grace_minutes": 1,
"provider_id": "예시값",
"fail_mode": "예시값",
"key": "예시값",
"scope": "예시값",
"target": "예시값",
"purpose": "예시값",
"priority": 1,
"conditions": [
"예시값"
],
"applies_to": "예시값"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.policies.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 본인인증 정책을 수정합니다. `auth:sanctum` + `core.admin.identity.policies.update` 관리자 권한이 필요합니다. `source_type='admin'` 정책은 모든 필드를 편집할 수 있으나, 선언형 정책(core/module/plugin) 은 `enabled`·`grace_minutes`·`provider_id`·`fail_mode`·`conditions`·`purpose`·`applies_to`·`priority` 화이트리스트("어떻게 인증할지") 만 허용되고 `key`/`scope`/`target`("어디서 인증할지") 은 확장 지점 식별자라 변경이 차단됩니다. 편집한 필드는 `user_overrides` 에 append 되어 시더 재실행 시 보존됩니다. 허용 필드가 하나도 없으면 422(nothing_to_update) 를 반환합니다. 확장은 `core.identity_policy.update_validation_rules` 필터 훅으로 검증을 확장할 수 있습니다.
### POST /api/admin/identity/policies/{id}/reset-field
- **라우트명**: `api.admin.identity.policies.reset-field`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityPolicyController@resetField`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.policies.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| field | body | string | 예 | `enabled`, `grace_minutes`, `provider_id`, `fail_mode`, `conditions`, `purpose`, `applies_to`, `priority` | 기본값으로 되돌릴 대상 필드명 (해당 필드의 운영자 재정의 해제 후 선언 기본값 복원) |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity_policy.reset_field_validation_rules`).
**요청 예시**
```http
POST /api/admin/identity/policies/{id}/reset-field HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"field": "enabled"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.policies.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 선언형 정책의 특정 필드에 대한 운영자 재정의(`user_overrides`) 를 해제하고 선언 기본값으로 즉시 복원합니다. `auth:sanctum` + `core.admin.identity.policies.update` 관리자 권한이 필요합니다. `field` 는 재정의 가능 필드(`enabled`, `grace_minutes`, `provider_id`, `fail_mode`, `conditions`, `purpose`, `applies_to`, `priority`) 중 하나여야 합니다. `source_type='admin'` 정책은 선언 기본값이 없어 403 을 반환하며 선언형 정책(core/module/plugin) 에만 의미가 있습니다. 관리자 편집 화면의 "↺ 기본값으로 되돌리기" 버튼이 호출하는 엔드포인트입니다.
### GET /api/admin/identity/providers
- **라우트명**: `api.admin.identity.providers.index`
- **컨트롤러**: `App\Http\Controllers\Api\Admin\Identity\AdminIdentityProviderController@index`
- **인증/권한**: `auth:sanctum` + `permission:core.admin.identity.providers.read`
**요청 파라미터**
_요청 파라미터 없음._
**요청 예시**
```http
GET /api/admin/identity/providers HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | string | `g7:core.mail` | 기본 키 (내부 식별자) |
| label | string | `이메일` | 표시용 라벨 |
| channels | array | `["email"]` | 이 프로바이더가 지원하는 전송 채널 식별자 목록 |
| channel_labels | object | `{"email":"이메일"}` | 채널 식별자 → 사람이 읽는 표시 라벨 맵 (다국어 처리, UI 표시용) |
| render_hint | string | `text_code` | 프론트 challenge 렌더 방식 힌트 (text_code: 코드 입력 UI / link: 링크 클릭 유도 / external_redirect: 외부 인증 페이지 이동) |
| is_available | boolean | `true` | available 여부 |
| abilities | object | `{"can_update":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
| settings_schema | object | `{"code_length":{"label":"인증 코드 길이","type":"integer","defa…` | 관리자 설정 UI 반복 렌더용 설정 스키마 (필드별 label/type/default/options/help — 코드 길이·만료 시간 등) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": [
{
"id": "g7:core.mail",
"label": "이메일",
"channels": [
"email"
],
"channel_labels": {
"email": "이메일"
},
"render_hint": "text_code",
"is_available": true,
"abilities": {
"can_update": true
},
"settings_schema": {
"code_length": {
"label": "인증 코드 길이",
"type": "integer",
"default": 6,
"min": 4,
"max": 10,
"help": "발송되는 숫자 코드의 자릿수 (기본 6, 최소 4, 최대 10)."
},
"from_address": {
"label": "발신자 주소",
"type": "string",
"default": null,
"help": "비어 있으면 시스템 기본 발신자를 사용합니다."
}
}
},
{
"id": "inicis",
"label": "KG이니시스 본인확인",
"channels": [
"ipin"
],
"channel_labels": {
"ipin": "아이핀"
},
"render_hint": "text_code",
"is_available": true,
"abilities": {
"can_update": true
},
"settings_schema": {
"is_test_mode": {
"label": "테스트 모드",
"type": "boolean",
"default": true
},
"test_mid": {
"label": "Test MID",
"type": "text",
"default": "INIiasTest"
},
"test_api_key": {
"label": "Test API Key",
"type": "password",
"default": "TGdxb2l3enJDWFRTbTgvREU3MGYwUT09"
},
"live_mid": {
"label": "Live MID (SRB prefix)",
"type": "text",
"default": ""
},
"live_api_key": {
"label": "Live API Key",
"type": "password",
"default": ""
},
"duplicate_field": {
"label": "Duplicate Field",
"type": "radio",
"options": [
"di",
"ci"
],
"default": "di"
},
"duplicate_block_enabled": {
"label": "중복 가입 차단",
"description": "활성화 시 본인인증을 통과한 사람이 이전에 다른 이메일로 가입한 적이 있으면 가입을 거부합니다. 가족 휴대폰 공유 또는 B2B 시나리오 등에서 한 사람이 여러 계정을 가입해야 한다면 비활성화하세요. 이 설정과 무관하게 동일 이메일 재가입은 항상 차단됩니다 (코어 기본 동작).",
"type": "toggle",
"default": true
}
}
}
]
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`core.admin.identity.providers.read`)이 없는 경우 |
**설명** 등록된 IDV 프로바이더 목록을 각 프로바이더의 설정 스키마(`settings_schema`) 와 함께 반환합니다. `auth:sanctum` + `core.admin.identity.providers.read` 관리자 권한이 필요합니다. 각 프로바이더의 `getSettingsSchema()` 결과를 `core.identity.settings_schema` 필터 훅으로 확장 가능하게 통과시키므로, 관리자 프로바이더 설정 카드(코드 길이·만료 시간 등)를 스키마 기반으로 반복 렌더링할 때 사용합니다. 설정 스키마가 없는 공개용 목록은 `GET /api/identity/providers` 를 사용합니다.
### POST /api/identity/callback/{providerId}
- **라우트명**: `api.identity.callback`
- **컨트롤러**: `\App\Http\Controllers\Api\Identity\IdentityVerificationController@callback`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근)
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| providerId | path | string | 예 | — | 대상 provider의 식별자 |
| challenge_id | body | string | 예 | max 64 | challenge 식별자 |
| code | body | string | 아니오 | max 512 | 외부 프로바이더가 콜백으로 전달한 인가 코드/인증 코드 |
| token | body | string | 아니오 | max 1024 | 인증/검증 토큰 |
| state | body | string | 아니오 | max 512 | 콜백 위변조 방지용 state 값 (요청 시 발급한 값과 대조) |
| redirect_url | body | string | 아니오 | max 2048 | 인증 완료 후 되돌아갈 URL (open redirect 방지 위해 same-origin 만 허용) |
**요청 예시**
```http
POST /api/identity/callback/{providerId} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json
{
"challenge_id": "예시값",
"code": "예시값",
"token": "{YOUR_TOKEN}",
"state": "예시값",
"redirect_url": "https://example.com"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 외부 IDV 프로바이더(외부 인증 SDK/OAuth-style provider) 가 사용자 브라우저를 앱으로 되돌려 보내는 redirect 콜백 진입점입니다. `auth:sanctum` 인증이 필요합니다. body/query 의 `challenge_id` 를 추출해 `IdentityVerificationService::handleProviderCallback` 에 위임하며, 클라이언트가 stash 한 `return` 쿼리 유무와 성공 여부에 따라 응답이 갈립니다 — 성공+return: 302 로 `{return}?verification_token=...&challenge_id=...`, 성공+return 없음: 200 JSON `{ verification_token }`, 실패+return: 302 로 `{return}?identity_error={failure_code}`, 실패+return 없음: 422 JSON. `return` URL 은 open redirect 방지를 위해 same-origin(또는 `/` 상대경로) 만 허용하고 protocol-relative(`//`) 는 차단합니다.
### POST /api/identity/challenges
- **라우트명**: `api.identity.challenges.request`
- **컨트롤러**: `\App\Http\Controllers\Api\Identity\IdentityVerificationController@request`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근) + `permission:core.identity.request`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| purpose | body | string | 예 | max 64 | 인증 목적 (signup/password_reset/self_update/sensitive_action/login 또는 모듈 정의 목적) |
| target | body | array | 아니오 | — | 비로그인 게스트의 인증 대상 (target.email 또는 target.phone — 로그인 사용자는 본인으로 자동 설정) |
| provider_id | body | string | 아니오 | max 64 | provider 식별자 |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity.request_validation_rules`).
**요청 예시**
```http
POST /api/identity/challenges HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json
{
"purpose": "예시값",
"target": [
"예시값"
],
"provider_id": "예시값"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 403 | Forbidden | 요구 권한(`core.identity.request`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 본인인증 challenge(인증 시도) 를 시작합니다. `auth:sanctum` + `core.identity.request` 권한이 필요합니다. 로그인 사용자는 인증 대상이 자동으로 본인이 되며, 비로그인 게스트(Mode B 가입 흐름) 는 `target.email` 또는 `target.phone` 을 반드시 제공해야 하고 없으면 422(missing_target) 를 반환합니다. `provider_id` 미지정 시 목적에 매핑된 기본 프로바이더가 선택됩니다. `IdentityVerificationService::start` 가 IP·User-Agent 등 컨텍스트와 함께 challenge 를 생성하고 성공 시 201 로 challenge 리소스(render_hint 등 포함) 를 반환합니다. 확장은 `core.identity.request_validation_rules` 필터 훅으로 파라미터를 추가할 수 있습니다.
### GET /api/identity/challenges/{challenge}
- **라우트명**: `api.identity.challenges.show`
- **컨트롤러**: `\App\Http\Controllers\Api\Identity\IdentityVerificationController@show`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근)
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| challenge | path | string | 예 | — | 대상 challenge의 식별자 |
**요청 예시**
```http
GET /api/identity/challenges/006209fd-1b6c-40aa-a38f-9b907f1a4bca HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | string | `006209fd-1b6c-40aa-a38f-9b907f1a4bca` | 기본 키 (내부 식별자) |
| status | string | `requested` | requested\|sent\|processing\|verified\|failed\|expired\|cancelled\|policy_violation_logged |
| provider_id | string | `g7:core.mail` | 프로바이더 식별자 (예: g7:core.mail, kcp) |
| purpose | string | `sensitive_action` | 인증 목적 (signup\|password_reset\|self_update\|sensitive_action\|login\|*module-defined*) — 코어 5종은 App\Enums\IdentityVerificationPurpose enum, 모듈/플러그인은 declaredPurposes 레지스트리 |
| render_hint | string | `text_code` | 프론트 렌더 힌트 (text_code\|link\|external_redirect) |
| expires_at | string | `2026-07-20T20:11:14+00:00` | expires 일시 |
| max_attempts | integer | `5` | 허용 최대 시도 횟수 (정책 상수). 누적 시도 횟수(attempts)는 잠금 직전까지 시도 횟수를 맞춰 보는 데 쓰일 수 있어 본 응답에 포함하지 않는다 |
| public_payload | array | `[]` | 프론트 렌더에 필요한 공개 안전 페이로드 (민감 metadata 제외, 프로바이더별 UI 힌트 — 없으면 빈 배열) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": {
"id": "006209fd-1b6c-40aa-a38f-9b907f1a4bca",
"status": "requested",
"provider_id": "g7:core.mail",
"purpose": "sensitive_action",
"render_hint": "text_code",
"expires_at": "2026-07-20T20:11:14+00:00",
"max_attempts": 5,
"public_payload": []
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** challenge 의 공개 상태를 폴링 조회합니다(engine-v1.46.0+). `auth:sanctum` 인증이 필요합니다. Stripe Identity/토스인증 push/외부 redirect 콜백 대기처럼 verify 즉시 응답을 받지 못하는 비동기 검증 흐름에서 클라이언트가 상태(verified/failed/expired 등) 를 추적하기 위한 엔드포인트입니다. `IdentityVerificationService::getStatus` 가 공개 안전 항목만 노출하며(시도 횟수 상세·코드 본체·metadata 미노출), challenge 를 찾지 못하면 404 를 반환합니다.
### POST /api/identity/challenges/{challenge}/cancel
- **라우트명**: `api.identity.challenges.cancel`
- **컨트롤러**: `\App\Http\Controllers\Api\Identity\IdentityVerificationController@cancel`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근) + `permission:core.identity.cancel`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| challenge | path | string | 예 | — | 대상 challenge의 식별자 |
**요청 예시**
```http
POST /api/identity/challenges/006209fd-1b6c-40aa-a38f-9b907f1a4bca/cancel HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 403 | Forbidden | 요구 권한(`core.identity.cancel`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** 진행 중인 challenge 를 취소합니다. `auth:sanctum` + `core.identity.cancel` 권한이 필요합니다. 라우트 모델 바인딩 + PermissionMiddleware 의 scope=self 가드로 로그인 사용자는 본인 challenge 만 취소할 수 있으며, 비로그인 게스트는 guest 역할 권한으로 진입합니다(모달 취소 시 audit trail 정합용). `IdentityVerificationService::cancel` 이 처리하고 대상 challenge 가 없으면 404 를 반환합니다. 사용자가 인증 모달을 닫을 때 서버 상태를 cancelled 로 남겨 이력 정합성을 맞추는 데 사용합니다.
### POST /api/identity/challenges/{challenge}/verify
- **라우트명**: `api.identity.challenges.verify`
- **컨트롤러**: `\App\Http\Controllers\Api\Identity\IdentityVerificationController@verify`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근) + `permission:core.identity.verify`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| challenge | path | string | 예 | — | 대상 challenge의 식별자 |
| code | body | string | 아니오 | max 16 | 사용자가 입력한 인증 코드 (text_code 흐름 — 메일/SMS 로 받은 숫자 코드) |
| token | body | string | 아니오 | max 256 | 인증/검증 토큰 |
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.identity.verify_validation_rules`).
**요청 예시**
```http
POST /api/identity/challenges/006209fd-1b6c-40aa-a38f-9b907f1a4bca/verify HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json
{
"code": "예시값",
"token": "{YOUR_TOKEN}"
}
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 403 | Forbidden | 요구 권한(`core.identity.verify`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
**설명** challenge 를 검증(인증 완료) 합니다. `auth:sanctum` + `core.identity.verify` 권한이 필요합니다. 라우트 모델 바인딩 + PermissionMiddleware 의 scope=self 가드로 로그인 사용자는 본인 challenge 만 검증하며, 비로그인 게스트는 guest 역할 권한으로 진입합니다(Mode B 가입 흐름). `code`(text_code 흐름) 또는 `token`(link/redirect 흐름) 을 전달하고 `IdentityVerificationService::verify` 가 처리합니다. 실패 시 422 로 `failure_code` 와 서버 기준 `attempts`/`max_attempts` 를 함께 내려 클라이언트의 "남은 시도 횟수" UI 를 서버와 동기화하며, 성공 시 후속 민감 작업에 제출할 `verification_token` 을 반환합니다. 확장은 `core.identity.verify_validation_rules` 필터 훅으로 파라미터를 추가할 수 있습니다.
### GET /api/identity/policies/resolve
- **라우트명**: `api.identity.policies.resolve`
- **컨트롤러**: `App\Http\Controllers\Api\Identity\IdentityVerificationController@resolvePolicy`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근)
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| scope | query | string | 예 | max 32 | 조회 범위 한정 키 |
| target | query | string | 예 | max 255 | 정책 매칭 대상 (scope 와 함께 해석 — 라우트명/URI 패턴, 훅 이름, 또는 custom key) |
**요청 예시**
```http
GET /api/identity/policies/resolve?scope=%EC%98%88%EC%8B%9C%EA%B0%92&target=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
```
**응답 필드** (`data` 내부)
**응답 예시**
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
**설명** 지정한 `scope`+`target` 조합에 매칭되는 본인인증 정책 요약을 반환합니다(프론트엔드 프리페치용). `auth:sanctum` 인증이 필요합니다. `IdentityPolicyService::resolve` 로 정책을 찾아 활성(`enabled`) 정책이 없으면 `data: null` 을, 있으면 UI 힌트에 필요한 최소 필드(`policy_key`, `scope`, `target`, `purpose`, `provider_id`, `grace_minutes`, `applies_to`, `fail_mode`) 만 반환하고 민감 필드는 노출하지 않습니다. 레이아웃 마운트 시 "이 페이지에서 IDV 가 요구될 수 있는 API" 를 미리 파악해 버튼 배지("확인 필요") 같은 UI 힌트를 표시할 때 사용합니다.
### GET /api/identity/providers
- **라우트명**: `api.identity.providers.index`
- **컨트롤러**: `App\Http\Controllers\Api\Identity\IdentityVerificationController@providers`
- **인증/권한**: 공개 (인증 불필요)
**요청 파라미터**
_요청 파라미터 없음._
**요청 예시**
```http
GET /api/identity/providers HTTP/1.1
Host: api.example.com
Accept: application/json
```
**응답 필드** (`data` 내부)
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | string | `g7:core.mail` | 기본 키 (내부 식별자) |
| label | string | `이메일` | 표시용 라벨 |
| channels | array | `["email"]` | 이 프로바이더가 지원하는 전송 채널 식별자 목록 |
| channel_labels | object | `{"email":"이메일"}` | 채널 식별자 → 사람이 읽는 표시 라벨 맵 (다국어 처리, UI 표시용) |
| render_hint | string | `text_code` | 프론트 challenge 렌더 방식 힌트 (text_code: 코드 입력 UI / link: 링크 클릭 유도 / external_redirect: 외부 인증 페이지 이동) |
| is_available | boolean | `true` | available 여부 |
| abilities | object | `{"can_update":false}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": [
{
"id": "g7:core.mail",
"label": "이메일",
"channels": [
"email"
],
"channel_labels": {
"email": "이메일"
},
"render_hint": "text_code",
"is_available": true,
"abilities": {
"can_update": false
}
},
{
"id": "inicis",
"label": "KG이니시스 본인확인",
"channels": [
"ipin"
],
"channel_labels": {
"ipin": "아이핀"
},
"render_hint": "text_code",
"is_available": true,
"abilities": {
"can_update": false
}
}
]
}
```
**에러 응답**
_대표 에러 없음 (공개 조회). 인증·권한 미요구 엔드포인트로 도메인 특이 에러를 반환하지 않습니다._
**설명** 등록된 IDV 프로바이더의 공개 메타데이터 목록을 반환합니다. 공개 엔드포인트로 인증이 필요하지 않으며, 비로그인 가입 흐름에서도 접근합니다. `IdentityVerificationManager::all()` 의 각 프로바이더를 `ProviderResource` 로 직렬화해 id·label·channels·render_hint·is_available 등만 노출하고, 관리자용과 달리 `settings_schema` 는 포함하지 않습니다. 인증 모달이 사용 가능한 프로바이더 선택지를 표시할 때 사용합니다.
### GET /api/identity/purposes
- **라우트명**: `api.identity.purposes.index`
- **컨트롤러**: `App\Http\Controllers\Api\Identity\IdentityVerificationController@purposes`
- **인증/권한**: 공개 (인증 불필요)
**요청 파라미터**
_요청 파라미터 없음._
**요청 예시**
```http
GET /api/identity/purposes HTTP/1.1
Host: api.example.com
Accept: application/json
```
**응답 필드** (`data` 내부)
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | string | `signup` | 기본 키 (내부 식별자) |
| label | string | `회원가입 인증` | 표시용 라벨 |
| description | string | `신규 가입자의 이메일/전화번호 소유 확인.` | 설명 (다국어 필드는 로케일별 값 객체) |
| default_provider | string | `g7:core.mail` | 이 목적에 매핑된 기본 프로바이더 ID (요청 시 provider_id 미지정이면 이 값 사용, 미설정 시 null) |
| allowed_channels | array | `["mail","sms"]` | 이 목적에서 사용 가능한 전송 채널 목록 |
| source_type | string | `core` | 목적 출처 (core: 코어 기본 5종 / module / plugin — 어느 확장이 선언했는지) |
| source_identifier | string | `core` | 출처 식별자 (목적을 선언한 확장의 identifier) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "messages.success",
"data": [
{
"id": "signup",
"label": "회원가입 인증",
"description": "신규 가입자의 이메일/전화번호 소유 확인.",
"default_provider": "g7:core.mail",
"allowed_channels": [
"mail",
"sms"
],
"source_type": "core",
"source_identifier": "core"
},
{
"id": "password_reset",
"label": "비밀번호 재설정",
"description": "비밀번호를 잊은 사용자가 본인 확인 후 재설정.",
"default_provider": "g7:core.mail",
"allowed_channels": [
"mail",
"sms"
],
"source_type": "core",
"source_identifier": "core"
},
{
"id": "self_update",
"label": "자기 정보 변경",
"description": "로그인 사용자가 이메일/전화 등 본인 정보를 변경할 때.",
"default_provider": "g7:core.mail",
"allowed_channels": [
"mail",
"sms"
],
"source_type": "core",
"source_identifier": "core"
},
{
"id": "sensitive_action",
"label": "민감 작업",
"description": "계정 탈퇴·관리자 작업 등 재인증이 필요한 시점.",
"default_provider": "g7:core.mail",
"allowed_channels": [
"mail",
"sms"
],
"source_type": "core",
"source_identifier": "core"
},
{
"id": "login",
"label": "로그인 2단계 인증",
"description": "2단계 인증을 켰을 때 비밀번호 확인 뒤 한 단계를 더 요구.",
"default_provider": null,
"allowed_channels": [
"email"
],
"source_type": "core",
"source_identifier": "core"
},
{
"id": "checkout_verification",
"label": "결제 시 본인 확인",
"description": "결제 진행 전 성인/본인 확인이 필요한 경우 사용됩니다.",
"default_provider": null,
"allowed_channels": [
"email",
"sms",
"ipin"
],
"source_type": "module",
"source_identifier": "sirsoft-ecommerce"
},
{
"id": "inicis.adult_verification",
"label": "성인인증 (KG이니시스 본인확인 전용)",
"description": "반드시 KG이니시스 provider 로만 매핑하세요. 메일/SMS provider 는 생년월일을 반환하지 않아 성인 여부 판정이 불가능합니다. 잘못 매핑 시 비성인 사용자에게 19금 컨텐츠가 노출될 수 있습니다.",
"default_provider": "inicis",
"allowed_channels": [
"ipin"
],
"source_type": "plugin",
"source_identifier": "sirsoft-verification_kginicis"
}
]
}
```
**에러 응답**
_대표 에러 없음 (공개 조회). 인증·권한 미요구 엔드포인트로 도메인 특이 에러를 반환하지 않습니다._
**설명** 등록된 인증 목적(purpose) 목록을 반환합니다. 공개 엔드포인트로 인증이 필요하지 않습니다. `IdentityVerificationManager::getAllPurposes()` 로 코어 기본 5종(signup/password_reset/self_update/sensitive_action/login) + 활성 모듈/플러그인의 `getIdentityPurposes()` 선언 + `core.identity.purposes` 필터 훅(서드파티 동적 확장) 을 병합하며, 각 항목의 label/description 은 i18n 키·다국어 배열·평문 세 형태를 현재 로케일 문자열로 정규화해 내려줍니다. 각 목적의 기본 프로바이더·허용 채널·출처(source_type/source_identifier) 를 함께 반환하므로, 인증 UI 가 목적별 선택지와 문구를 구성할 때 사용합니다.