> ## 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

> Network communication architecture and data security policies for the ARGOS Identity Restful API (Server-to-Server).

## 1. Document Overview

### 1.1 Purpose

This document describes the network communication architecture and data security policies for the **Restful API** provided by ARGOS Identity (no UI; server-to-server communication).

### 1.2 Target Audience

* Information security and security review personnel at customer organizations
* Backend development teams performing API integration
* Compliance / audit departments

### 1.3 Scope

* Communication architecture from the customer server → ARGOS API
* TLS, authentication, authorization, and payload security
* Multi-tenant isolation, auditing, and compliance

***

## 2. Service Category Introduction

**Restful API** is one of the four categories offered by ARGOS, providing a **Server-to-Server API called directly by the customer's server without a UI**.

### 2.1 Key Features

* Standard REST conventions (GET / POST / PATCH / DELETE)
* JSON-based requests/responses
* Custom domain with ACM-issued TLS certificate
* Per-project API Key issuance and validation

### 2.2 Use Cases

* Customers operating their own UI who only need to query and manage KYC result data from ARGOS
* Bulk manipulation of KYC submission data from a back-office or management tool
* External data integration (migration, synchronization)

### 2.3 Key Endpoint Examples

| Method | Path          | Description                               |
| ------ | ------------- | ----------------------------------------- |
| GET    | `/Submission` | Query submissions (pagination supported)  |
| POST   | `/Submission` | Create a submission (including migration) |
| PATCH  | `/Submission` | Update submission information             |
| DELETE | `/Submission` | (Soft) delete a submission                |

(For the full endpoint specification, refer to the separate API documentation.)

***

## 3. Network Communication Flow

### 3.1 Call Structure

```mermaid theme={null}
flowchart TD
    C[Customer Server] -->|HTTPS POST/GET/PATCH/DELETE<br/>TLS 1.2+, x-api-key header| R53[AWS Route 53<br/>Custom Domain]
    R53 -->|DNS resolution| ACM[AWS Certificate Manager<br/>ACM]
    ACM -->|TLS termination| GW["AWS API Gateway<br/>① API Key validation<br/>② Optional Custom Authorizer (IP allowlist)"]
    GW --> H["Serverless API handler<br/>③ Project ID mapping / status validation<br/>④ Optional request body decryption<br/>⑤ DynamoDB CRUD (with DAX if applicable)<br/>⑥ Optional response body encryption"]
    H --> RES[API Gateway → Customer response]
```

### 3.2 Communication Stages

| Stage                | From                             | To                 | Protocol                    |
| -------------------- | -------------------------------- | ------------------ | --------------------------- |
| ① DNS resolution     | Customer server                  | AWS Route 53       | DNS over TLS / Standard DNS |
| ② API call           | Customer server                  | AWS API Gateway    | HTTPS (TLS 1.2+)            |
| ③ Handler invocation | API Gateway                      | Serverless handler | AWS internal (TLS)          |
| ④ Data operations    | Handler                          | DynamoDB           | TLS 1.2+ (AWS SDK + SigV4)  |
| ⑤ Response return    | Handler → API Gateway → Customer | HTTPS (TLS 1.2+)   |                             |

***

## 4. Communication Protocols and Standards

### 4.1 Transport Layer

* **TLS 1.2 or higher enforced** (API Gateway security policy)
* **AWS Certificate Manager (ACM)**-issued certificates used (auto-renewal)
* ARGOS custom domain (managed via Route 53)

### 4.2 HTTP Request Format

| Item                    | Value                                                                           |
| ----------------------- | ------------------------------------------------------------------------------- |
| Method                  | GET / POST / PATCH / DELETE                                                     |
| Content-Type (request)  | `application/json` (default) / `text/plain` (when encryption option is enabled) |
| Content-Type (response) | Same                                                                            |
| Encoding                | UTF-8                                                                           |

### 4.3 Required Request Headers

| Header         | Description                                      |
| -------------- | ------------------------------------------------ |
| `x-api-key`    | Unique API Key issued per project (**required**) |
| `Content-Type` | `application/json` or `text/plain`               |
| `Host`         | Custom domain issued by ARGOS                    |

***

## 5. Data Encryption

### 5.1 In Transit (Required)

* **HTTPS / TLS 1.2+** enforced
* TLS termination is handled by AWS API Gateway
* The API Gateway → handler segment also uses AWS internal TLS

### 5.2 Payload Encryption (Optional, per-project activation)

Customers who want additional protection for sensitive data can enable the following option.

| Item           | Value                                               |
| -------------- | --------------------------------------------------- |
| Activation     | Enable the `Data Encryption` project option         |
| Algorithm      | AES-256 (symmetric key)                             |
| Key derivation | Based on the project API Key seed                   |
| Scope          | Both request body and response body (bidirectional) |
| Content-Type   | `text/plain` (Base64-encoded ciphertext)            |

### 5.3 At Rest

* All data is protected by **DynamoDB server-side encryption**
* Sensitive identifying fields are additionally encrypted at the application layer using **AES-256 + AWS KMS Customer-managed Key**
* Object storage (images) is encrypted using **AWS S3 SSE-KMS**

***

## 6. Authentication and Authorization

### 6.1 Primary Authentication — API Gateway API Key

All Restful API calls must **pass API Key validation at the AWS API Gateway stage** before reaching the serverless handler.

| Item                  | Value                                                                |
| --------------------- | -------------------------------------------------------------------- |
| Issuance unit         | **Per-project (Project-specific)**                                   |
| Issuance method       | Issued by ARGOS when a new project is created                        |
| Delivery method       | HTTP Header `x-api-key`                                              |
| Validating party      | AWS API Gateway (validated before the serverless handler is invoked) |
| Missing or mismatched | Immediately rejected at the API Gateway stage (`403 Forbidden`)      |

### 6.2 Secondary Authentication (Optional) — IP Allowlist

Projects requiring additional security can enable an **IP Allowlist**.

* Register allowed IP ranges per project
* **AWS Lambda Authorizer** compares the client IP against the allowlist
* On mismatch, an IAM Deny Policy is returned → rejected by API Gateway
* If the allowlist is empty, there is no IP restriction (API Key alone is sufficient for authentication)

### 6.3 API Key Management Recommendations

* Never expose the API Key to clients (browsers, mobile apps)
* Store in a server-side secret store (e.g., AWS Secrets Manager)
* If leakage is suspected, notify ARGOS immediately and request re-issuance

***

## 7. Integrity and Tamper Prevention

| Segment                      | Method                                                |
| ---------------------------- | ----------------------------------------------------- |
| TLS channel                  | TLS 1.2+ built-in integrity (AEAD / HMAC)             |
| Payload (encryption mode)    | AES-256 + successful decryption → source verification |
| API Gateway input validation | Method / Path / Header automatic validation           |
| Serverless handler           | Field format, type, and range validation              |
| Internal calls               | AWS SigV4 signing                                     |

***

## 8. Access Control and Isolation

### 8.1 Network Layer

* External entry points are limited exclusively to **AWS API Gateway** (serverless handlers are not directly reachable from outside)
* API Gateway automatically applies AWS-managed DDoS protection (AWS Shield Standard)

### 8.2 Environment Separation

* Live / Test environment APIs are separated (separate API Keys, separate domains, separate data)
* Data movement between environments is performed only through an explicit migration procedure

### 8.4 Rate Limiting

* **AWS API Gateway Usage Plan** sets per-API-Key call limits
* Call control via Burst / Quota units
* Exceeding the limit returns `429 Too Many Requests`

***

## 9. Compliance

### 9.1 ARGOS Identity Held Certifications

* **ISO/IEC 27001** — International standard certification for information security management systems

### 9.2 AWS Infrastructure Certifications (Inherited)

The Restful API infrastructure (AWS API Gateway, Lambda, DynamoDB, Route 53, ACM, CloudFront, etc.) inherits the following certifications:

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

### 9.3 Data Subject Rights Response

* Procedures in place to respond to data subject rights requests (access, rectification, erasure, portability) under applicable privacy laws / GDPR
* The DELETE endpoint permanently deletes personal information in submission data

***

## Appendix A. Glossary

| Term              | Definition                                                          |
| ----------------- | ------------------------------------------------------------------- |
| TLS               | Transport Layer Security                                            |
| AES-256           | 256-bit Advanced Encryption Standard                                |
| API Gateway       | AWS-managed API gateway service                                     |
| API Key           | Identification key for API call authentication (issued per project) |
| ACM               | AWS Certificate Manager — TLS certificate management service        |
| Route 53          | AWS DNS management service                                          |
| Custom Authorizer | A user-defined authentication function attached to API Gateway      |
| IAM Policy        | AWS Identity and Access Management policy                           |
| Usage Plan        | API Gateway call limit configuration                                |
| Rate Limit        | Maximum call count per unit time                                    |
| Quota             | Total allowed calls per day/month                                   |
| Partition Key     | Data distribution key in DynamoDB                                   |
| AEAD              | Authenticated Encryption with Associated Data                       |
| SigV4             | AWS Signature Version 4                                             |

***

## Appendix B. Contact

For technical inquiries regarding this document, please contact ARGOS Identity through the sales or technical support channel.