## Common Integration guidelines Welcome to ZignSec's API documentation. Our APIs allow you to integrate identity verification, KYC, and AML services into your applications. --- ## Environments We maintain 2 environments: - **PROD** <https://gateway.zignsec.com> – for production usage - **TEST** <https://test-gateway.zignsec.com> – for tests (please contact our support if you need to run a massive/load test) ## Secure connection To ensure the security and integrity of data exchanged with our APIs, we enforce strict transport security measures. All API requests must be made over encrypted channels using modern, secure protocols. ### HTTPS enforcement All API endpoints are accessible **only via HTTPS**. Any attempts to connect using unencrypted HTTP will be rejected. ### TLS requirements We require **TLS 1.2 or higher** for all connections. Older versions (TLS 1.0 and 1.1) are not supported due to known vulnerabilities. ### Supported Cipher Suites Our API endpoints only allow strong, industry-recommended cipher suites, ensuring protection against cryptographic attacks. We follow best practices and exclude weak or deprecated ciphers. You can use <https://ciphersuite.info/> to do a quick check of the cipher suit - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 --- ## File Management Some ZignSec products require file uploads (e.g., documents, images) or return downloadable results (e.g., scanned document files). The file management capabilities in our API are designed to simplify this process. Key considerations: - **Short-term storage**: Files uploaded or generated through our APIs are retained for **48 hours** by default. - **Temporary reference model**: You can reference uploaded files in subsequent API requests via file IDs. - **Not for archival**: ZignSec is not intended for long-term file storage. If extended retention is required, please contact your Account Manager or ZignSec Support. These features ensure flexibility during processing without creating unnecessary storage overhead. --- ## Authentication ZignSec supports multiple authentication methods to secure your API requests: - **Subscription Key** – Easy-to-use header-based authentication. - **OAuth2 (OIDC)** – Token-based security for scalable applications. - **Two-Way SSL** – Mutual certificate authentication for enhanced security. Authentication failures may result in `401 Unauthorized` or `403 Forbidden` errors, especially during key rotation or token expiry. Implement retry logic where appropriate. ➡️ [Go to the Authentication page](Authentication.md) --- ## Error Handling ZignSec APIs follow standard HTTP status codes and include structured error responses for better troubleshooting. Newer APIs provide JSON error objects with `code`, `description`, and `statusCode`. You'll also find retry recommendations for transient errors like `429`, `502`, or `503`. ➡️ [Learn more about error messages](Error%20handling.md) --- ## Webhooks Webhooks will allow your system to receive real-time notifications for asynchronous events (e.g., document scan completed, verification succeeded). This functionality is under development and will be documented soon. ➡️ [Learn more about webhooks](Webhooks.md)