> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restful API

> ARGOS Identity Restful API(Server-to-Server)의 네트워크 통신 구조와 데이터 보안 정책.

## 1. 문서 개요

### 1.1 목적

Argos Identity가 제공하는 **Restful API** (UI 미포함, 서버-서버 통신 방식)의 네트워크 통신 구조와 데이터 보안 정책을 정리한 자료입니다.

### 1.2 대상 독자

* 고객사의 정보보호·보안 검토 담당자
* API 통합을 진행하는 백엔드 개발팀
* 컴플라이언스 / 감사 부서

### 1.3 범위

* 고객사 서버 → Argos API 의 통신 구조
* TLS, 인증, 권한 부여, 페이로드 보안
* 멀티테넌트 격리, 감사, 컴플라이언스

***

## 2. 서비스 카테고리 소개

**Restful API**는 Argos가 제공하는 4종 카테고리 중 하나로, **UI 없이 고객사 서버가 직접 호출하는 Server-to-Server API** 입니다.

### 2.1 주요 특징

* 표준 REST 규약 (GET / POST / PATCH / DELETE)
* JSON 기반 요청/응답
* 회사 자체 커스텀 도메인 + ACM 발급 TLS 인증서
* 프로젝트 단위 API Key 발급 및 검증

### 2.2 적용 사례

* 고객사가 자체 UI를 운영하면서 KYC 결과 데이터만 Argos로부터 조회·관리
* 백오피스/관리 도구에서 KYC 제출 데이터를 일괄 조작
* 외부 데이터 연동 (마이그레이션, 동기화)

### 2.3 주요 엔드포인트 예시

| Method | Path          | 설명                |
| ------ | ------------- | ----------------- |
| GET    | `/Submission` | 제출 조회 (페이지네이션 지원) |
| POST   | `/Submission` | 제출 생성 (마이그레이션 포함) |
| PATCH  | `/Submission` | 제출 정보 수정          |
| DELETE | `/Submission` | 제출 (소프트) 삭제       |

(전체 엔드포인트 명세는 별도 API 문서 참조)

***

## 3. 네트워크 통신 흐름

### 3.1 호출 구조

```mermaid theme={null}
flowchart TD
    C[고객사 서버] -->|HTTPS POST/GET/PATCH/DELETE<br/>TLS 1.2+, x-api-key 헤더| R53[AWS Route 53<br/>Custom Domain]
    R53 -->|DNS 해석| ACM[AWS Certificate Manager<br/>ACM]
    ACM -->|TLS 종료| GW["AWS API Gateway<br/>① API Key 검증<br/>② 옵션 Custom Authorizer (IP 화이트리스트)"]
    GW --> H["서버리스 API 핸들러<br/>③ Project ID 매핑 / 상태 검증<br/>④ 옵션 요청 본문 복호화<br/>⑤ DynamoDB CRUD (필요 시 DAX)<br/>⑥ 옵션 응답 본문 암호화"]
    H --> RES[API Gateway → 고객사 응답]
```

### 3.2 통신 단계

| 단계       | 출발                      | 도착               | 프로토콜                       |
| -------- | ----------------------- | ---------------- | -------------------------- |
| ① DNS 해석 | 고객사 서버                  | AWS Route 53     | DNS over TLS / 표준 DNS      |
| ② API 호출 | 고객사 서버                  | AWS API Gateway  | HTTPS (TLS 1.2+)           |
| ③ 핸들러 호출 | API Gateway             | 서버리스 핸들러         | AWS 내부 (TLS)               |
| ④ 데이터 조작 | 핸들러                     | DynamoDB         | TLS 1.2+ (AWS SDK + SigV4) |
| ⑤ 응답 반환  | 핸들러 → API Gateway → 고객사 | HTTPS (TLS 1.2+) |                            |

***

## 4. 통신 프로토콜 및 규약

### 4.1 전송 계층

* **TLS 1.2 이상 강제** (API Gateway 보안 정책)
* **AWS Certificate Manager (ACM)** 발급 인증서 사용 (자동 갱신)
* Argos 자체 도메인 (Route 53 관리)

### 4.2 HTTP 요청 형식

| 항목                | 값                                                    |
| ----------------- | ---------------------------------------------------- |
| Method            | GET / POST / PATCH / DELETE                          |
| Content-Type (요청) | `application/json` (기본) / `text/plain` (암호화 옵션 활성 시) |
| Content-Type (응답) | 동일                                                   |
| 인코딩               | UTF-8                                                |

### 4.3 필수 요청 헤더

| 헤더             | 설명                                 |
| -------------- | ---------------------------------- |
| `x-api-key`    | 프로젝트별 발급된 고유 API Key (**필수**)      |
| `Content-Type` | `application/json` 또는 `text/plain` |
| `Host`         | Argos가 발급한 커스텀 도메인                 |

***

## 5. 데이터 암호화

### 5.1 전송 중 (필수)

* **HTTPS / TLS 1.2+** 강제
* TLS 종료는 AWS API Gateway가 담당
* API Gateway → 핸들러 구간도 AWS 내부 TLS

### 5.2 페이로드 암호화 (옵션, 프로젝트별 활성)

민감 데이터를 추가 보호하려는 고객사는 다음 옵션을 활성화할 수 있습니다.

| 항목           | 값                             |
| ------------ | ----------------------------- |
| 활성화 방법       | 프로젝트 옵션 `데이터 암호화` 활성          |
| 알고리즘         | AES-256 (대칭 키)                |
| 키 도출         | 프로젝트 API Key 시드 기반            |
| 적용 범위        | 요청 본문 + 응답 본문 양방향             |
| Content-Type | `text/plain` (Base64 인코딩 암호문) |

### 5.3 저장 시

* 모든 데이터는 **DynamoDB 서버측 암호화**
* 민감 식별 필드는 **AES-256 + AWS KMS Customer-managed Key** 로 애플리케이션 계층 추가 암호화
* 객체 스토리지(이미지)는 **AWS S3 SSE-KMS** 로 암호화

***

## 6. 인증 및 인가

### 6.1 1차 인증 — API Gateway API Key

모든 Restful API 호출은 **AWS API Gateway 단계에서 API Key 검증을 통과해야** 서버리스 핸들러까지 도달할 수 있습니다.

| 항목        | 값                                        |
| --------- | ---------------------------------------- |
| 발급 단위     | **프로젝트 단위 (Project-specific)**           |
| 발급 방식     | Argos가 신규 프로젝트 생성 시 발급                   |
| 전달 방법     | HTTP Header `x-api-key`                  |
| 검증 주체     | AWS API Gateway (서버리스 핸들러 호출 전 검증)       |
| 누락 또는 불일치 | API Gateway 단계에서 즉시 거부 (`403 Forbidden`) |

### 6.2 2차 인증 (옵션) — IP 화이트리스트

추가 보안이 필요한 프로젝트는 **IP Allowlist** 를 활성화할 수 있습니다.

* 프로젝트별 허용 IP 범위 등록
* **AWS Lambda Authorizer** 가 클라이언트 IP를 화이트리스트와 대조
* 불일치 시 IAM Deny Policy 반환 → API Gateway가 거부
* 화이트리스트가 비어 있으면 IP 제한 없음 (API Key만으로 인증)

### 6.3 API Key 관리 권장 사항

* API Key는 절대 클라이언트(브라우저, 모바일 앱)에 노출하지 말 것
* 서버 측 비밀(Secret) 저장소(AWS Secrets Manager 등)에 보관
* 누출 의심 시 Argos에 즉시 통보 후 재발급 요청

***

## 7. 무결성 및 위·변조 방지

| 구간                | 방식                            |
| ----------------- | ----------------------------- |
| TLS 채널            | TLS 1.2+ 내장 무결성 (AEAD / HMAC) |
| 페이로드 (암호화 모드)     | AES-256 + 복호화 성공 → 출처 검증      |
| API Gateway 입력 검증 | Method / Path / Header 자동 검증  |
| 서버리스 핸들러          | 필드 형식·타입·범위 검증                |
| 내부 호출             | AWS SigV4 서명                  |

***

## 8. 접근 통제 및 격리

### 8.1 네트워크 계층

* 외부 진입점은 **AWS API Gateway** 만으로 한정 (서버리스 핸들러는 외부 직접 도달 불가)
* API Gateway는 AWS 관리형 DDoS 보호(AWS Shield Standard) 자동 적용

### 8.2 환경 분리

* Live / Test 환경 API 분리 (별도 API Key, 별도 도메인, 별도 데이터)
* 환경 간 데이터 이동은 명시적 마이그레이션 절차로만 수행

### 8.4 Rate Limiting

* **AWS API Gateway Usage Plan** 으로 API Key 별 호출 한도 설정
* Burst / Quota 단위로 호출 제어
* 한도 초과 시 `429 Too Many Requests` 응답

***

## 9. 컴플라이언스

### 9.1 Argos Identity 보유 인증

* **ISO/IEC 27001** — 정보보호관리체계 국제표준 인증

### 9.2 AWS 인프라 인증 (상속)

Restful API 인프라(AWS API Gateway, Lambda, DynamoDB, Route 53, ACM, CloudFront 등)는 다음 인증을 상속합니다:

* SOC 1 / SOC 2 / SOC 3
* ISO 27001 / 27017 / 27018
* PCI-DSS Level 1
* HIPAA Eligible
* FedRAMP Moderate

### 9.3 데이터 주체 권리 대응

* 개인정보 보호법 / GDPR 기반 데이터 주체 권리 요청(열람·정정·삭제·이전) 대응 절차 운영
* DELETE 엔드포인트는 제출 데이터의 개인정보 영구 삭제

***

## 부록 A. 용어 정리

| 용어                | 정의                                            |
| ----------------- | --------------------------------------------- |
| TLS               | Transport Layer Security                      |
| AES-256           | 256-bit Advanced Encryption Standard          |
| API Gateway       | AWS 관리형 API 게이트웨이 서비스                         |
| API Key           | API 호출 인증용 식별 키 (프로젝트별 발급)                    |
| ACM               | AWS Certificate Manager — TLS 인증서 관리 서비스      |
| Route 53          | AWS DNS 관리 서비스                                |
| Custom Authorizer | API Gateway에 연결하는 사용자 정의 인증 함수                |
| IAM Policy        | AWS Identity and Access Management 정책         |
| Usage Plan        | API Gateway 호출 한도 설정                          |
| Rate Limit        | 단위 시간당 호출 한도                                  |
| Quota             | 일/월 단위 호출 총 한도                                |
| Partition Key     | DynamoDB의 데이터 분산 키                            |
| AEAD              | Authenticated Encryption with Associated Data |
| SigV4             | AWS Signature Version 4                       |

***

## 부록 B. 문의

본 문서에 대한 기술적 질의는 Argos Identity 영업/기술 지원 채널로 연락주시기 바랍니다.