SDK Quick Start - Essential Examples

This page provides 6 minimal examples (10-15 lines each) demonstrating core SDK patterns without boilerplate. Each example links to complete production-ready flows with error handling, resource management, and edge cases.

Goal: Get your first SDK call working in under 2 minutes.

Example 1: Encrypt Any File (Auto-Detection - Recommended)

// ONE method handles any file size
AuthenticatedSdk sdk = factory.authenticateApplication(clientId, secret);
sdk.encryptFile("my-key", input, output);  // ← Auto-selects compact vs streaming

How it works: The SDK automatically selects compact or streaming format based on input size versus the server-discovered limit (GET /api/v3/crypto/limits → maxPlaintextBytes, default 4 MB). A compact call that hits the limit falls back to streaming automatically on 413.

Complete production example: Flow 1 - Asymmetric Encrypt/Decrypt

Example 2: Decrypt Any Format (Auto-Detection)

// Works with Compact, General JSON (composite KEM keys) and streaming formats
sdk.decryptFile(encrypted, decrypted);  // ← Auto-detects input format

How it works: The SDK inspects the start of the file to determine if it holds a Compact JWE token, a General JSON JWE (a JSON object, written for composite KEM keys), or streaming chunks.

Complete production example: Flow 1 - Asymmetric Encrypt/Decrypt

Example 3: Compact Token for APIs (below the configured limit)

// Single-line JWE for REST API transmission
sdk.encryptFileCompact("api-key", config, output);
String jwe = Files.readString(output);  // ← One-line Base64 token
apiClient.post("/api/store", jwe);

When to use: Small payloads for microservices, JSON messages, unit tests.

Complete production example: Flow 5 - ML-KEM-512 Compact

Example 4: Large File Streaming (Constant Memory)

// 500 GB file, 64 KB RAM
sdk.encryptFileStream("archive-key", largeFile, output);

When to use: GB-scale backups, log archives, media files.

Complete production example: Flow 1 - ML-KEM-512 Streaming Encrypt/Decrypt

Example 5: Quantum-Resistant Encryption

// Composite hybrid key (classical + PQC), provisioned in the control plane.
// The SDK encrypts against the existing kid — it does not create the key.
// Below the size limit the file holds a General JSON JWE (one recipient per component).
sdk.encryptFile("hybrid-key", secret, encrypted);

Provision first: Create the COMPOSITE_KEM_COMBINE key (e.g. X25519+ML-KEM-768) in the Admin Console or with ankasecure-km keys create, and grant the actor ENCRYPT on it. See Before You Integrate.

When to use: Standards alignment (the hybrid cryptographic algorithms of NIST CSWP 39 §3.2.4, the hybrid approach the GSA PQC Buyer's Guide lists as a consideration, EU/BSI/ANSSI standards).

Complete production example: Flow 18 - Composite Hybrid Keys

Example 6: Migrate RSA to Post-Quantum

// Zero-exposure migration (never touches plaintext)
sdk.reencryptFile("old-rsa-key", "new-mlkem-key", oldCiphertext, newCiphertext);

When to use: Upgrade legacy RSA/EC ciphertexts to ML-KEM without decrypting.

Complete production example: Flow 4 - Asymmetric Re-encrypt

Next Steps

• Complete Examples (21 Flows) - All integration patterns organized by category
• File Operation Patterns - Deep dive into auto-detection, streaming, compact modes
• Usage Guide - Setup, authentication, and API reference
• Security Best Practices - Key lifecycle, session management, error handling

Pattern Quick Reference

Tip: Start with auto-detection methods (encryptFile, decryptFile) for 90% of use cases. Only use explicit format methods when you have specific requirements.