API Integration

Purpose: Integration patterns for migration across Admin API, Core API, Auth API, and License Server

Version: 3.0.0

Overview of API Integration

Migration operations span multiple ANKASecure APIs, each with specific responsibilities:

Integration Pattern: Coordinated operations across APIs ensure secure, compliant, and auditable migrations.

Admin API Integration

Tenant Provisioning During Migration

Purpose: Ensure tenant exists before importing keys

Workflow:

sequenceDiagram
    participant Admin as Admin User
    participant AuthAPI as Auth API
    participant AdminAPI as Admin API

    Admin->>AuthAPI: POST /auth/login<br/>{username, password}
    AuthAPI-->>Admin: JWT token<br/>(platform admin scope)

    Admin->>AdminAPI: POST /admin/tenants<br/>{tenantId, name}
    AdminAPI->>AdminAPI: Create tenant record<br/>Initialize keystore

    AdminAPI-->>Admin: 201 Created<br/>{tenantId, status}

    Admin->>AuthAPI: POST /auth/login<br/>{tenantId, username, password}
    AuthAPI-->>Admin: JWT token<br/>(tenant scope + migration scopes)

    Admin->>AdminAPI: POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore<br/>multipart: metadata + keystore<br/>Bearer: tenant JWT
    AdminAPI->>AdminAPI: Store key in tenant keystore

    AdminAPI-->>Admin: 200 OK<br/>{keys, certificates, skipped, failures}

Key Points:

• Tenant must exist before importing keys
• JWT token must have tenant-specific scopes
• Each tenant has isolated keystore

User Management

Purpose: Create users with migration permissions

Required Scopes for migration operations:

Migration User Scopes:
  - SCOPE_key_management.importPrivateKeyPkcs12   # Import PKCS#12
  - SCOPE_key_management.exportKey                # Export keys
  - SCOPE_key_management.importKey                # Import JWK/DER
  - SCOPE_interoperability.verifySignature        # Utility verify (keyless)
  - SCOPE_interoperability.encrypt                # Utility encrypt (keyless)
  - SCOPE_key_management.generateKey              # Generate PQC keys
  - SCOPE_crypto.encrypt                          # Encrypt operations
  - SCOPE_crypto.decrypt                          # Decrypt operations

Create Migration User:

POST /api/v3/admin/platform/users
{
  "username": "migration-admin",
  "email": "[email protected]",
  "scopes": [
    "SCOPE_key_management.importPrivateKeyPkcs12",
    "SCOPE_key_management.generateKey",
    "SCOPE_crypto.encrypt",
    "SCOPE_crypto.decrypt"
  ]
}

Application Lifecycle

Purpose: Register applications that will use migrated keys

Workflow:

1. Create application in Admin API
2. Generate app credentials (client_id, client_secret)
3. Authenticate app via Auth API
4. Use migrated keys via Core API

Core API Integration

Using Imported Keys in Operations

Purpose: Leverage imported keys for regular cryptographic operations

Seamless Integration:

graph LR
    ImportedKey["Imported RSA Key<br/>kid: rsa-legacy"] -->|Stored in| Keystore["Tenant Keystore"]
    NativeKey["Native ML-KEM Key<br/>kid: mlkem-2025"] -->|Stored in| Keystore

    App["Application"] -->|Decrypt| DecryptAPI["POST /api/v3/crypto/decrypt<br/>kid: rsa-legacy"]
    App -->|Encrypt| EncryptAPI["POST /api/v3/crypto/encrypt<br/>kid: mlkem-2025"]

    DecryptAPI -->|Uses| ImportedKey
    EncryptAPI -->|Uses| NativeKey

    style ImportedKey fill:#ffcccc,stroke:#333,stroke-width:2px
    style NativeKey fill:#51cf66,stroke:#333,stroke-width:2px

Key Insight: Applications use imported and native keys identically—no special handling required.

Mixed Key Type Operations

Purpose: Support applications using both legacy and PQC keys

Example: Hybrid application during migration period

{
  "operations": [
    {
      "operation": "decrypt",
      "kid": "rsa-encryption-legacy",
      "ciphertext": "RSA_CIPHERTEXT..."
    },
    {
      "operation": "encrypt",
      "kid": "encryption-pqc-2025",
      "plaintext": "NEW_DATA..."
    },
    {
      "operation": "verify",
      "kid": "rsa-signing-legacy",
      "signature": "RSA_SIGNATURE..."
    },
    {
      "operation": "sign",
      "kid": "signing-pqc-2025",
      "payload": "NEW_DOCUMENT..."
    }
  ]
}

Result: All operations execute successfully with appropriate keys.

Legacy Key Restrictions

Purpose: Enforce operational restrictions on imported keys

Restriction Enforcement:

graph TD
    Operation["Crypto Operation Request"] -->|Check| Key{"Load Key"}

    Key -->|legacy=false| NativeKey["Native/Valid Imported<br/>All operations allowed"]
    Key -->|legacy=true| LegacyKey["Expired/Revoked Imported<br/>Restricted operations"]

    NativeKey -->|Check| OpCheck1["ensureKeyOpsAllowed"]
    LegacyKey -->|Check| OpCheck2["ensureKeyOpsAllowed"]

    OpCheck1 -->|encrypt in keyOps| AllowEnc["✅ Allow encryption"]
    OpCheck2 -->|encrypt NOT in keyOps| DenyEnc["❌ Deny encryption<br/>KeyOperationNotAllowed"]

    style AllowEnc fill:#51cf66,stroke:#333,stroke-width:2px
    style DenyEnc fill:#ff6b6b,stroke:#333,stroke-width:2px

Operation Permission Matrix (from key lifecycle policy):

Streaming Operations

Purpose: Re-encrypt large files without memory limitations

Streaming Re-encryption API:

sequenceDiagram
    participant Client
    participant StreamAPI as Streaming API
    participant LegacyKey as RSA Key
    participant PQCKey as ML-KEM Key

    Client->>StreamAPI: POST /api/v3/crypto/stream/reencrypt?newKid=mlkem-2025<br/>header: JWET header (kid rsa-legacy)<br/>file: large-archive.enc

    loop For each chunk (4 MB)
        StreamAPI->>LegacyKey: Decrypt chunk
        LegacyKey-->>StreamAPI: Plaintext chunk

        StreamAPI->>PQCKey: Encrypt chunk
        PQCKey-->>StreamAPI: Ciphertext chunk

        StreamAPI-->>Client: Stream ciphertext chunk
    end

    StreamAPI-->>Client: Conversion complete<br/>File re-encrypted

Benefits:

• ✅ No memory limitations (handles TB-sized files)
• ✅ Plaintext never fully exposed (only chunks)
• ✅ Progress tracking (per-chunk reporting)
• ✅ Resumable (checkpoint after each chunk)

See: Streaming Operations^* for detailed API documentation

License Server Integration

License Impact of Imported Keys

Purpose: Ensure imported keys count toward license quotas appropriately

Licensing Rules:

Quota Check Before Import:

graph TD
    ImportRequest["Import Request"] -->|Check| License{"License<br/>Available?"}

    License -->|Quota available| Proceed["✅ Proceed with import"]
    License -->|Quota exhausted| Deny["❌ Deny import<br/>HTTP 402 Payment Required"]

    Proceed -->|Import| Store["Store key in keystore"]
    Store -->|Increment| Counter["Increment usage counter"]

    Counter -->|Report| LicenseServer["License Server<br/>Track usage"]

    style Proceed fill:#51cf66,stroke:#333,stroke-width:2px
    style Deny fill:#ff6b6b,stroke:#333,stroke-width:2px

Usage Tracking

Purpose: Monitor cryptographic operations during migration

Tracked Metrics:

• Key operations: encrypt, decrypt, sign, verify per key
• Data volume: Bytes encrypted/decrypted
• Signature count: Signatures created/verified
• API calls: Total requests per tenant

Usage Report Example:

{
  "tenantId": "enterprise-tenant",
  "period": "2025-01-01 to 2025-01-31",
  "keysImported": 45,
  "keysGenerated": 45,
  "operations": {
    "encrypt": 125000,
    "decrypt": 89000,
    "sign": 67000,
    "verify": 234000
  },
  "dataProcessed": "1.2 TB",
  "licenseStatus": "COMPLIANT"
}

Quota Management

Purpose: Avoid quota exhaustion during large migrations

Quota Planning:

Recommendation: Upgrade license tier before migration if approaching quota limits.

Auth API Integration

JWT Scopes for Migration

Purpose: Secure migration operations with proper authorization

Scope Hierarchy:

graph TD
    PlatformAdmin["Platform Admin<br/>Highest privilege"] -->|Can perform| AllOps["All Operations"]

    TenantAdmin["Tenant Admin"] -->|Can perform| TenantOps["Tenant-scoped Operations"]

    AppUser["Application User"] -->|Can perform| LimitedOps["Limited Operations"]

    AllOps -->|Includes| Import["Import keys<br/>any tenant"]
    AllOps -->|Includes| Export["Export keys<br/>any tenant"]

    TenantOps -->|Includes| TenantImport["Import keys<br/>own tenant only"]
    TenantOps -->|Includes| TenantExport["Export keys<br/>own tenant only"]

    LimitedOps -->|Includes| UtilityOps["Utility operations<br/>verify, encrypt with external keys"]

    style PlatformAdmin fill:#ff6b6b,stroke:#333,stroke-width:2px
    style TenantAdmin fill:#ffd43b,stroke:#333,stroke-width:2px
    style AppUser fill:#51cf66,stroke:#333,stroke-width:2px

Service-to-Service Authentication

Purpose: Secure communication between migration scripts and APIs

Application-token pattern (for automated migration scripts):

Private key material enters the platform only inside a PKCS#12 or JKS keystore, through the tenant-scoped keystore import on Admin API (scope migration.importKeystore). Admin API forwards it to Core API service-to-service; Core API's own keystore route is not reachable by a client.

sequenceDiagram
    participant Script as Migration Script
    participant AuthAPI as Auth API
    participant AdminAPI as Admin API
    participant CoreAPI as Core API

    Script->>AuthAPI: POST /api/v3/auth/token<br/>grant_type=client_credentials

    AuthAPI->>AuthAPI: Validate client credentials
    AuthAPI-->>Script: JWT token<br/>(app scopes)

    Script->>AdminAPI: POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore<br/>multipart: metadata + keystore (+ password)<br/>Bearer: JWT

    AdminAPI->>AdminAPI: Validate JWT<br/>(iss, aud, exp, nbf) and tenant
    AdminAPI->>CoreAPI: S2S keystore import

    AdminAPI-->>Script: 200 OK<br/>{summary, keys, certificates, skipped, failures}

Authentication Methods for Migration:

1. User JWT: Interactive migration via UI/CLI
2. App JWT (client_credentials): Automated migration scripts

End-to-End Integration Example

Complete Migration Workflow Across APIs

Scenario: Migrate 200 applications with coordinated API operations

sequenceDiagram
    participant Admin
    participant AuthAPI as Auth API
    participant AdminAPI as Admin API
    participant CoreAPI as Core API
    participant LicenseAPI as License Server

    Note over Admin: Pre-Migration Setup

    Admin->>AuthAPI: Login (platform admin)
    AuthAPI-->>Admin: JWT (platform scope)

    Admin->>AdminAPI: POST /tenants<br/>{tenantId: enterprise}
    AdminAPI-->>Admin: 201 Created

    Admin->>AdminAPI: POST /users<br/>{migration admin user}
    AdminAPI-->>Admin: 201 Created

    Admin->>AdminAPI: POST /applications<br/>{200 app registrations}
    AdminAPI-->>Admin: 201 Created (bulk)

    Note over Admin: Migration Execution

    Admin->>AuthAPI: Login (tenant admin)
    AuthAPI-->>Admin: JWT (tenant + migration scopes)

    loop For each application
        Admin->>AdminAPI: POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore<br/>multipart: metadata + keystore

        AdminAPI->>LicenseAPI: Check quota
        LicenseAPI-->>AdminAPI: ✅ Quota available

        AdminAPI->>AdminAPI: Import key<br/>Store in tenant keystore

        AdminAPI->>LicenseAPI: Record usage
        LicenseAPI-->>AdminAPI: Usage recorded

        AdminAPI-->>Admin: 200 OK<br/>{keys, skipped, failures}
    end

    Note over Admin: Post-Migration

    Admin->>CoreAPI: GET /keys (list all imported)
    CoreAPI-->>Admin: List of 200 keys

    Admin->>LicenseAPI: GET /licenses/status
    LicenseAPI-->>Admin: Usage: 200 keys<br/>Quota: 5000 keys

Error Handling Across Services

Coordinated Error Responses:

graph TD
    Request["Migration Request"] -->|1. Auth| AuthCheck{"Auth API<br/>Valid JWT?"}

    AuthCheck -->|No| AuthError["401 Unauthorized<br/>Invalid or expired token"]
    AuthCheck -->|Yes| AdminCheck{"Admin API<br/>Tenant exists?"}

    AdminCheck -->|No| TenantError["404 Not Found<br/>Tenant not provisioned"]
    AdminCheck -->|Yes| LicenseCheck{"License API<br/>Quota available?"}

    LicenseCheck -->|No| QuotaError["402 Payment Required<br/>Quota exhausted"]
    LicenseCheck -->|Yes| CoreOp{"Core API<br/>Import valid?"}

    CoreOp -->|No| ImportError["400/422 Error<br/>Invalid PKCS#12 or cert"]
    CoreOp -->|Yes| Success["201 Created<br/>Key imported successfully"]

    style AuthError fill:#ff6b6b,stroke:#333,stroke-width:2px
    style TenantError fill:#ff6b6b,stroke:#333,stroke-width:2px
    style QuotaError fill:#ffd43b,stroke:#333,stroke-width:2px
    style ImportError fill:#ff6b6b,stroke:#333,stroke-width:2px
    style Success fill:#51cf66,stroke:#333,stroke-width:2px

Audit Trail

Purpose: Track migration operations across all APIs

Audit Events Logged:

Correlation IDs: All logs include X-Correlation-ID for tracing operations across services.

Related Documentation

• Overview & Strategy - Migration capabilities overview
• Complete Enterprise Migration^* - End-to-end migration workflow
• Monitoring & Validation - Cross-service monitoring
• Admin API Documentation^* - Admin API reference
• Auth API Documentation^* - Authentication patterns

Version: 3.0.0
Last Updated: 2025-12-24 Status: Production Ready