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

> Arquitectura de comunicación de red y políticas de seguridad de datos de la Restful API (Server-to-Server) de ARGOS Identity.

## 1. Descripción general del documento

### 1.1 Propósito

Este documento es un recurso que resume la arquitectura de comunicación de red y las políticas de seguridad de datos de la **Restful API** (sin UI, comunicación servidor a servidor) proporcionada por ARGOS Identity.

### 1.2 Destinatarios

* Responsables de revisión de seguridad e información de las organizaciones clientes
* Equipos de desarrollo backend que realizan integración de API
* Departamentos de cumplimiento normativo / auditoría

### 1.3 Alcance

* Arquitectura de comunicación del servidor del cliente → API de ARGOS
* TLS, autenticación, autorización y seguridad de payload
* Aislamiento multitenant, auditoría y cumplimiento normativo

***

## 2. Introducción a la categoría de servicio

**Restful API** es una de las 4 categorías ofrecidas por ARGOS, y es una **API Server-to-Server que el servidor del cliente invoca directamente sin UI**.

### 2.1 Características principales

* Convenciones REST estándar (GET / POST / PATCH / DELETE)
* Solicitudes y respuestas basadas en JSON
* Dominio personalizado propio de la empresa + certificado TLS emitido por ACM
* Emisión y validación de API Key por unidad de proyecto

### 2.2 Casos de uso

* La organización cliente opera su propia UI y solo consulta o gestiona datos de resultados KYC desde ARGOS
* Manipulación masiva de datos de envíos KYC desde herramientas de back-office o administración
* Integración con datos externos (migración, sincronización)

### 2.3 Ejemplos de endpoints principales

| Method | Path          | Descripción                                    |
| ------ | ------------- | ---------------------------------------------- |
| GET    | `/Submission` | Consulta de envíos (con soporte de paginación) |
| POST   | `/Submission` | Creación de envíos (incluyendo migración)      |
| PATCH  | `/Submission` | Modificación de información de envíos          |
| DELETE | `/Submission` | Eliminación (suave) de envíos                  |

(Para la especificación completa de endpoints, consulte la documentación de API separada)

***

## 3. Flujo de comunicación de red

### 3.1 Estructura de llamada

```mermaid theme={null}
flowchart TD
    C[Servidor del cliente] -->|HTTPS POST/GET/PATCH/DELETE<br/>TLS 1.2+, cabecera x-api-key| R53[AWS Route 53<br/>Custom Domain]
    R53 -->|Resolución DNS| ACM[AWS Certificate Manager<br/>ACM]
    ACM -->|Terminación TLS| GW["AWS API Gateway<br/>① Validación de API Key<br/>② Custom Authorizer opcional (lista blanca de IP)"]
    GW --> H["Manejador API serverless<br/>③ Mapeo de Project ID / Validación de estado<br/>④ Descifrado opcional del cuerpo de solicitud<br/>⑤ CRUD DynamoDB (con DAX si es necesario)<br/>⑥ Cifrado opcional del cuerpo de respuesta"]
    H --> RES[API Gateway → Respuesta al cliente]
```

### 3.2 Etapas de comunicación

| Etapa                   | Origen                            | Destino              | Protocolo                   |
| ----------------------- | --------------------------------- | -------------------- | --------------------------- |
| ① Resolución DNS        | Servidor del cliente              | AWS Route 53         | DNS over TLS / DNS estándar |
| ② Llamada a la API      | Servidor del cliente              | AWS API Gateway      | HTTPS (TLS 1.2+)            |
| ③ Llamada al manejador  | API Gateway                       | Manejador serverless | Interno AWS (TLS)           |
| ④ Manipulación de datos | Manejador                         | DynamoDB             | TLS 1.2+ (AWS SDK + SigV4)  |
| ⑤ Retorno de respuesta  | Manejador → API Gateway → cliente | HTTPS (TLS 1.2+)     |                             |

***

## 4. Protocolos y normas de comunicación

### 4.1 Capa de transporte

* **TLS 1.2 o superior obligatorio** (política de seguridad de API Gateway)
* Uso de certificados emitidos por **AWS Certificate Manager (ACM)** (renovación automática)
* Dominio propio de ARGOS (gestionado en Route 53)

### 4.2 Formato de solicitudes HTTP

| Elemento                 | Valor                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| Method                   | GET / POST / PATCH / DELETE                                                                 |
| Content-Type (solicitud) | `application/json` (por defecto) / `text/plain` (cuando la opción de cifrado está activada) |
| Content-Type (respuesta) | Igual                                                                                       |
| Codificación             | UTF-8                                                                                       |

### 4.3 Cabeceras de solicitud obligatorias

| Cabecera       | Descripción                                          |
| -------------- | ---------------------------------------------------- |
| `x-api-key`    | API Key única emitida por proyecto (**obligatoria**) |
| `Content-Type` | `application/json` o `text/plain`                    |
| `Host`         | Dominio personalizado emitido por ARGOS              |

***

## 5. Cifrado de datos

### 5.1 En tránsito (obligatorio)

* **HTTPS / TLS 1.2+** obligatorio
* La terminación TLS está a cargo de AWS API Gateway
* El tramo API Gateway → manejador también usa TLS interno de AWS

### 5.2 Cifrado de payload (opcional, activación por proyecto)

Las organizaciones clientes que deseen protección adicional para datos sensibles pueden activar la siguiente opción.

| Elemento              | Valor                                                    |
| --------------------- | -------------------------------------------------------- |
| Método de activación  | Activar la opción de proyecto `Cifrado de datos`         |
| Algoritmo             | AES-256 (clave simétrica)                                |
| Derivación de clave   | Basada en semilla de API Key del proyecto                |
| Alcance de aplicación | Bidireccional: cuerpo de solicitud + cuerpo de respuesta |
| Content-Type          | `text/plain` (texto cifrado codificado en Base64)        |

### 5.3 En reposo

* Todos los datos se protegen con **cifrado lado servidor de DynamoDB**
* Los campos de identificación sensibles se cifran adicionalmente en la capa de aplicación con **AES-256 + AWS KMS Customer-managed Key**
* El almacenamiento de objetos (imágenes) se cifra con **AWS S3 SSE-KMS**

***

## 6. Autenticación y autorización

### 6.1 Autenticación primaria — API Gateway API Key

Todas las llamadas a la Restful API deben **superar la validación de API Key en la etapa AWS API Gateway** para llegar al manejador serverless.

| Elemento                | Valor                                                                    |
| ----------------------- | ------------------------------------------------------------------------ |
| Unidad de emisión       | **Por proyecto (Project-specific)**                                      |
| Método de emisión       | ARGOS emite la clave al crear un nuevo proyecto                          |
| Método de transmisión   | Cabecera HTTP `x-api-key`                                                |
| Entidad de validación   | AWS API Gateway (validación previa a la llamada al manejador serverless) |
| Ausencia o discrepancia | Rechazo inmediato en la etapa API Gateway (`403 Forbidden`)              |

### 6.2 Autenticación secundaria (opcional) — Lista blanca de IP

Los proyectos que requieran seguridad adicional pueden activar la **IP Allowlist**.

* Registro del rango de IP permitidas por proyecto
* **AWS Lambda Authorizer** compara la IP del cliente con la lista blanca
* En caso de discrepancia, se devuelve IAM Deny Policy → API Gateway rechaza la solicitud
* Si la lista blanca está vacía, no hay restricción de IP (solo se autentica con API Key)

### 6.3 Recomendaciones de gestión de API Key

* La API Key no debe exponerse nunca en el cliente (navegador, aplicación móvil)
* Almacenar en un almacén de secretos (Secret) del lado del servidor (AWS Secrets Manager, etc.)
* En caso de sospecha de filtración, notificar inmediatamente a ARGOS y solicitar reemisión

***

## 7. Integridad y prevención de alteraciones

| Tramo                                | Método                                                |
| ------------------------------------ | ----------------------------------------------------- |
| Canal TLS                            | Integridad integrada en TLS 1.2+ (AEAD / HMAC)        |
| Payload (modo cifrado)               | AES-256 + descifrado exitoso → verificación de origen |
| Validación de entrada en API Gateway | Validación automática de Method / Path / Header       |
| Manejador serverless                 | Validación de formato, tipo y rango de campos         |
| Llamadas internas                    | Firma AWS SigV4                                       |

***

## 8. Control de acceso y aislamiento

### 8.1 Capa de red

* El punto de entrada externo se limita exclusivamente a **AWS API Gateway** (el manejador serverless no es accesible directamente desde el exterior)
* API Gateway aplica automáticamente protección DDoS gestionada por AWS (AWS Shield Standard)

### 8.2 Separación de entornos

* Separación de API para entornos Live / Test (API Key independiente, dominio independiente, datos independientes)
* El movimiento de datos entre entornos solo se realiza mediante procedimiento explícito de migración

### 8.4 Rate Limiting

* Se establece un límite de llamadas por API Key mediante **AWS API Gateway Usage Plan**
* Control de llamadas por unidades de Burst / Quota
* Ante superación del límite, respuesta `429 Too Many Requests`

***

## 9. Cumplimiento normativo

### 9.1 Certificaciones obtenidas por ARGOS Identity

* **ISO/IEC 27001** — Certificación de norma internacional de gestión de seguridad de la información

### 9.2 Certificaciones de infraestructura AWS (heredadas)

La infraestructura de Restful API (AWS API Gateway, Lambda, DynamoDB, Route 53, ACM, CloudFront, etc.) hereda las siguientes certificaciones:

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

### 9.3 Derechos del interesado

* Procedimientos de respuesta a solicitudes de derechos del interesado (acceso, rectificación, supresión, portabilidad) basados en la Ley de Protección de Datos Personales / GDPR
* El endpoint DELETE realiza la eliminación definitiva de los datos personales del envío

***

## Apéndice A. Glosario de términos

| Término           | Definición                                                                             |
| ----------------- | -------------------------------------------------------------------------------------- |
| TLS               | Transport Layer Security                                                               |
| AES-256           | 256-bit Advanced Encryption Standard                                                   |
| API Gateway       | Servicio de gateway de API gestionado por AWS                                          |
| API Key           | Clave de identificación para autenticación de llamadas a la API (emitida por proyecto) |
| ACM               | AWS Certificate Manager — servicio de gestión de certificados TLS                      |
| Route 53          | Servicio de gestión DNS de AWS                                                         |
| Custom Authorizer | Función de autenticación personalizada conectada a API Gateway                         |
| IAM Policy        | Política de AWS Identity and Access Management                                         |
| Usage Plan        | Configuración de límite de llamadas en API Gateway                                     |
| Rate Limit        | Límite de llamadas por unidad de tiempo                                                |
| Quota             | Límite total de llamadas por día o mes                                                 |
| Partition Key     | Clave de distribución de datos en DynamoDB                                             |
| AEAD              | Authenticated Encryption with Associated Data                                          |
| SigV4             | AWS Signature Version 4                                                                |

***

## Apéndice B. Consultas

Para consultas técnicas sobre este documento, póngase en contacto con el canal de soporte técnico y comercial de ARGOS Identity.