API Reference

Purpose: Complete API endpoint reference for migration and interoperability operations

Base Paths: the interoperability utilities are Core API operations under /api/v3/interoperability, and the PKCS#7 utilities under /api/v3/migration; importing key material is a control-plane operation and is reached on the Admin API, under /api/v3/admin/tenants/{tenantId}/keys/.

Version: 3.0.0

Authentication: JWT Bearer token required for all endpoints

Endpoint Overview

The migration, interoperability and import endpoints:

PKCS#7 Analysis and Conversion

The four PKCS#7 operations are documented in full, with examples and the error contract, on PKCS#7 Conversion. This section lists the members of their contract.

Every signer and every recipient is carried. A SignedData with N signers converts to a JWS with one signature per signer, an EnvelopedData with M recipients to a JWE with one recipient entry per recipient, and a SignedAndEnvelopedData (RFC 2315 §11) to a JWE whose plaintext is a JWS with one signature per outer signer. One conversion accepts at most 16 signers and recipients together; above it the request is refused 422 ACTOR_LIMIT_EXCEEDED before any key is looked up.

Convert request members

These are the only members. Any other — at the root or inside algorithmPolicy, on both operations — is refused 400 invalid-input with a detail naming the member, never its value; that includes validateCertificates, validateTimestamp and algorithmPolicy.contentEncryptionUpgrade, which the request does not define. The CMS signature of every re-signed signer is always verified, and the content is always re-encrypted under A256GCM.

Convert response members (compact operation)

The streaming operation returns the JOSE output itself — no metadata — as described in PKCS#7 Conversion.

Analyze response: recommendations

migrationPath (CONVERT_TO_{JWS,JWE,JWE_JWS}_{COMPACT,JSON}), requiredKeys[] (one entry per actor, purpose signing or encryption, named by issuerDN and serialNumber), decryptionRequirement (ONE_RECIPIENT_PRIVATE_KEY for an encrypted structure) and estimatedComplexity. See Analyze Operations.

Analyze request and response

The compact analyze request carries pkcs7Data only; the streaming request's metadata part is an empty JSON object, {}, still required and first. Analysis takes no key and no option, and a member a request does not define is refused 400 invalid-input naming it. detectedFormat.structure is SignedData, EnvelopedData or SignedAndEnvelopedData. limits.maxActors is the actor bound above — the value the conversion enforces — so a client reads it from the analysis instead of hard-coding 16.

POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore

Purpose

Import cryptographic private keys and certificate chains from PKCS#12 (.p12 or .pfx) or JKS (.jks) keystores.

Endpoint Details

POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore
Content-Type: multipart/form-data
Authorization: Bearer {jwt-token}
Scope: SCOPE_migration.importKeystore

The request carries a metadata JSON part, a keystore file part and an optional password part. The parameters below are fields of the metadata part, except password, which is its own part.

Request Parameters

KeystoreImportMetadata precedence for an alias's purpose: per-alias purposeMappings → keystore-level purpose → AUTO (derived from the certificate KeyUsage). AUTO that remains ambiguous fails closed with HTTP 422 purpose-required. DUAL projects one private keypair onto two single-purpose kids (<kid>-enc, <kid>-sig).

Request Example

curl -sS -X POST \
  "$ANKA_BASE_URL/api/v3/admin/tenants/$TENANT_ID/keys/import-keystore" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'metadata={"kid":"enterprise-signing-2024","validationMode":"STRICT","kidStrategy":"AUTO","kidMappings":null,"purpose":"AUTO","purposeMappings":{"legacy-rsa":"DUAL"}};type=application/json' \
  -F "[email protected]" \
  -F "password=$KEYSTORE_PASSWORD"

Response - Success (201 Created)

{
  "kid": "enterprise-signing-2024",
  "kty": "RSA",
  "alg": "RSA-4096",
  "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
  "keyOps": ["sign", "verify"],
  "exportable": true,
  "createdAt": "2025-12-19T10:30:00Z",
  "expiresAt": "2026-12-31T23:59:59Z",
  "softLimitExpiration": "2026-11-30T23:59:59Z",
  "usageCount": 0,
  "status": "active",
  "origin": "IMPORTED",
  "restricted": false,
  "hash": "D4E5F6789012345678901234567890ABCDEF0123"
}

Response - Error

400 Bad Request:

{
  "type": "/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Invalid Base64 encoding in keystoreContent"
}

413 Payload Too Large:

{
  "type": "/errors/payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "Keystore file size (25165824 bytes) exceeds the maximum allowed size (20971520 bytes)."
}

422 Unprocessable Entity:

{
  "type": "/errors/certificate-validation",
  "title": "Certificate Validation Failed",
  "status": 422,
  "detail": "Certificate expired on 2023-12-31T23:59:59Z",
  "errors": [
    {
      "type": "EXPIRED",
      "message": "Certificate expired on 2023-12-31T23:59:59Z",
      "severity": "ERROR"
    }
  ]
}

See: Error Reference for what each failure type means and what to change. The step-by-step import procedure is delivered with a licensed deployment.

POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore/analyze (preview)

Purpose

Read-only preview of a keystore import. Parses the uploaded keystore in memory and returns, per alias, the detected algorithm and the KeyUsage-derived purpose (or AMBIGUOUS) without persisting anything — no key is stored and no audit event is written. The console import wizard calls it to render a per-alias purpose preview and prompt only on ambiguous aliases. An ambiguous alias yields detectedPurpose: AMBIGUOUS and HTTP 200 (never 422 — the 422 belongs to the committing import path).

Scope

SCOPE_migration.importKeystore — the same scope as the committing import. Previewing a keystore is not a separate privilege: anything you may import, you may look at first.

Request

multipart/form-data, tenant in the path, with three parts:

Response - Success (200 OK)

{
  "aliases": [
    { "alias": "data-encryption", "kid": "acme-enc", "algorithm": "RSA-2048", "detectedPurpose": "ENCRYPT_DECRYPT", "keyUsage": ["encrypt", "decrypt"], "privateKeyPresent": true },
    { "alias": "legal-signing", "kid": "acme-sig", "algorithm": "RSA-2048", "detectedPurpose": "SIGN_VERIFY", "keyUsage": ["sign", "verify"], "privateKeyPresent": true },
    { "alias": "legacy-rsa", "kid": "acme-legacy", "algorithm": "RSA-2048", "detectedPurpose": "AMBIGUOUS", "keyUsage": [], "privateKeyPresent": true }
  ]
}

The response wraps the per-alias entries in an aliases array. It contains no key material — only alias, kid, algorithm, the KeyUsage-derived detectedPurpose, the resolved keyUsage operations (empty when AMBIGUOUS), and privateKeyPresent.

POST /api/v3/interoperability/verify

Purpose

Verify a detached JWS signature using a caller-supplied public key without storing it.

Endpoint Details

POST /api/v3/interoperability/verify
Content-Type: multipart/form-data
Authorization: Bearer {jwt-token}
Scope: SCOPE_interoperability.verifySignature

Request Parameters (Multipart)

Part 1: metadata (application/json)

Part 2: file (application/octet-stream)

• Binary payload that was originally signed

Request Example

curl -X POST /api/v3/interoperability/verify \
  -H "Authorization: Bearer $TOKEN" \
  -F 'metadata={"kty":"ML-DSA","alg":"ML-DSA-87","publicKey":"...","signatureBase64":"..."}' \
  -F '[email protected]'

Accepted alg Values

The JWS was signed by a third party, so its protected alg is honoured (RFC 7515 §4.1.1): it selects the verification scheme, and it must be a registered JWS algorithm that fits the supplied key.

Refused with 422 application/problem+json before any verification: none, an absent alg, an HMAC alg such as HS256, a composite alg (a composite signature is not a single-key signature), an alg that does not fit the key (such as ES256 on a P-384 key), and an ECDSA signature that is not its curve's fixed length. The detail names neither the alg nor the key.

Response - Success (200 OK)

{
  "valid": true,
  "signatureResults": []
}

Response - Verification Failed (200 OK)

A signature that does not verify is still HTTP 200, with valid: false.

{
  "valid": false,
  "signatureResults": []
}

See: Utility Operations for detailed documentation

POST /api/v3/interoperability/encrypt

Purpose

Encrypt plaintext using a caller-supplied public key without storing it.

Endpoint Details

POST /api/v3/interoperability/encrypt
Content-Type: multipart/form-data
Authorization: Bearer {jwt-token}
Scope: SCOPE_interoperability.encrypt

Request Parameters (Multipart)

Part 1: metadata (application/json)

Part 2: file (application/octet-stream)

• Binary plaintext to encrypt

Request Example

curl -X POST /api/v3/interoperability/encrypt \
  -H "Authorization: Bearer $TOKEN" \
  -F 'metadata={"kty":"ML-KEM","alg":"ML-KEM-768","publicKey":"..."}' \
  -F '[email protected]' \
  --output encrypted-bundle.mime

Response - Success (200 OK)

Content-Type: multipart/mixed; boundary=----ankatech-{uuid}

Part 1: Detached JWE header (application/jose+json)
Part 2: Ciphertext (application/octet-stream)

See: Utility Operations for detailed documentation

GET /api/v3/admin/tenants/{tenantId}/keys/{kid}/export

Purpose

Retrieve the public material and operational metadata of a key, for external system integration or to compare a tenant key with a certificate held elsewhere. Export is an Admin API operation.

Endpoint Details

GET /api/v3/admin/tenants/{tenantId}/keys/{kid}/export
Authorization: Bearer {jwt-token}
Scope: SCOPE_admin.keys.read

Path Parameters

Request Example

curl -X GET "$ANKA_BASE_URL/api/v3/admin/tenants/$TENANT_ID/keys/prod-signing-key/export" \
  -H "Authorization: Bearer $TOKEN"

Response - Success (200 OK)

Public material only: private key material is never returned, in any key shape. For a simple asymmetric key publicKey is the Base64 SubjectPublicKeyInfo; a symmetric key (kty oct) has no publicKey; a composite key returns its component public keys in components[].

{
  "kid": "prod-signing-key",
  "kty": "ML-DSA",
  "alg": "ML-DSA-87",
  "type": "SIMPLE",
  "publicKey": "MIIHsjALBglghkgBZQMEAxMDggehAE...",
  "keyOps": ["sign", "verify"],
  "exportable": true,
  "origin": "GENERATED",
  "restricted": false,
  "status": "active",
  "createdAt": "2025-01-15T10:20:00Z",
  "expiresAt": "2030-01-15T10:20:00Z",
  "usageCount": 1542
}

Errors

• 400 invalid-input — the key is non-exportable (exportable false); no key material is returned.
• 404 not-found — the kid does not exist for the tenant. A kid of another tenant, and a path naming another tenant, answer the same 404.

POST /api/v3/admin/tenants/{tenantId}/keys/import-key

Purpose

Import key from JWK (JSON Web Key) or DER format.

Endpoint Details

POST /api/v3/admin/tenants/{tenantId}/keys/import-key
Content-Type: application/json
Authorization: Bearer {jwt-token}
Scope: SCOPE_migration.importKey

Request Parameters

Request Example

{
  "kid": "imported-ec-key",
  "kty": "EC",
  "alg": "ECDSA-P256",
  "publicKey": "MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE...",
  "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEH...",
  "keyOps": ["sign", "verify"]
}

Response - Success (201 Created)

{
  "kid": "imported-ec-key",
  "kty": "EC",
  "alg": "ECDSA-P256",
  "keyOps": ["sign", "verify"],
  "status": "active",
  "createdAt": "2025-12-24T10:00:00Z",
  "expiresAt": "2126-12-24T10:00:00Z"
}

Note: This endpoint is simpler than keystore import—no certificate validation, used for JWK/DER imports.

GET /api/v3/key-management/keys

Purpose

Query and filter keys in the tenant keystore with support for multiple filter criteria.

Endpoint Details

GET /api/v3/key-management/keys
Authorization: Bearer {jwt-token}
Scope: SCOPE_key_management.listKeys

Query Parameters

Request Examples

Get all imported keys:

GET /api/v3/key-management/keys?origin=IMPORTED

Get restricted keys (expired certificates):

GET /api/v3/key-management/keys?origin=IMPORTED&restricted=true

Get valid imported keys:

GET /api/v3/key-management/keys?origin=IMPORTED&restricted=false

Get all RSA keys:

GET /api/v3/key-management/keys?kty=RSA

Get every hybrid (composite) key:

GET /api/v3/key-management/keys?kty=COMPOSITE

A composite mode name is not a key type — ?kty=COMPOSITE_KEM_COMBINE is rejected with 400. The construction is read from each key's compositeMode field in the response.

Combine filters:

GET /api/v3/key-management/keys?origin=IMPORTED&kty=RSA&status=active

Response - Success (200 OK)

[
  {
    "kid": "imported-signing-2024",
    "kty": "RSA",
    "alg": "RSA-3072",
    "keyOps": ["sign", "verify"],
    "status": "active",
    "origin": "IMPORTED",
    "restricted": false,
    "createdAt": "2025-12-19T10:30:00Z",
    "expiresAt": "2026-12-31T23:59:59Z"
  },
  {
    "kid": "recovery-key",
    "kty": "RSA",
    "alg": "RSA-2048",
    "keyOps": ["encrypt", "decrypt"],
    "status": "expired",
    "origin": "IMPORTED",
    "restricted": true,
    "createdAt": "2025-12-15T08:00:00Z",
    "expiresAt": "2023-12-31T23:59:59Z"
  },
  {
    "kid": "hybrid-transport-2026",
    "kty": "COMPOSITE",
    "compositeMode": "COMPOSITE_KEM_COMBINE",
    "alg": "X25519+ML-KEM-768",
    "keyOps": ["encrypt", "decrypt"],
    "status": "active",
    "origin": "GENERATED",
    "restricted": false,
    "createdAt": "2026-01-08T09:15:00Z",
    "expiresAt": "2028-01-08T09:15:00Z"
  }
]

Field Definitions

origin:

• GENERATED: Key created natively by ANKASecure
• IMPORTED: Key imported from external keystore (PKCS#12/JKS)

restricted:

• false: Key can perform all operations defined in keyOps
• true: Key limited to decrypt and verify only (imported with expired certificate)

Restricted Key Behavior:

When restricted: true, attempts to use the key for operations other than decrypt/verify will fail:

{
  "type": "/errors/operation-not-allowed",
  "status": 400,
  "detail": "Operation 'encrypt' is not allowed for restricted key 'recovery-key'. Restricted keys (imported with expired certificates) are limited to decrypt and verify operations only."
}

Security Scopes Matrix

Scope Definitions

Scope Assignment Recommendations

Platform Administrator (highest privilege):

• ✅ All scopes (including importKeystore, importKey)
• Use for: Initial migration, tenant provisioning

Tenant Administrator:

• ✅ importKeystore, exportKey, importKey (tenant-scoped)
• ✅ Migration utility scopes
• Use for: Tenant-level migrations

Application User:

• ✅ Utility scopes only (verifySignatureUtilityStream, encryptUtilityStream)
• ❌ No import or export scopes
• Use for: Runtime interoperability operations

Size Limits & Constraints

Request Size Limits

"No API limit" is the API's own bound; a proxy in front of the deployment may cap uploads; see Behind a buffering proxy.

Increasing Keystore Size Limit

The maximum keystore size is a platform setting. The operator raises or lowers it in the Admin Console under Platform Settings → Cryptography & Trust → Migration & Trust, for example to 52428800 for 50 MB. The change applies to the next import, without a restart.

Accepted range: 1048576–104857600 bytes. A value outside it is refused on write.

Certificate Chain Limits

Error Response Reference

HTTP Status Codes

Error Response Format (RFC 7807)

All errors follow Problem Details for HTTP APIs standard:

{
  "type": "/errors/{error-category}",
  "title": "Human-Readable Title",
  "status": 400,
  "detail": "Specific error description",
  "instance": "/api/v3/admin/tenants/{tenantId}/keys/import-keystore",
  "errors": [
    {
      "type": "ERROR_CODE",
      "message": "Detailed error message",
      "severity": "ERROR"
    }
  ]
}

Common Error Types

Configuration Reference

Platform Settings

The operator sets these in the Admin Console under Platform Settings → Cryptography & Trust → Migration & Trust. A change applies to the next import, without a restart.

Trust Anchors and Revocation

Certificate chains are validated against the trusted CA certificates the operator installs on the deployment.

The import does not check certificate revocation status (CRL or OCSP). Check that a certificate is not revoked before you import it.

Fixed Limits

Validation Mode Comparison

In every mode the stored keyOps are derived from the certificate KeyUsage (single-purpose; the precedence is stated with the request parameters above); the restricted=true runtime gate additionally limits expired/IMPORT_ONLY keys to decrypt/verify.

Related Documentation

• Overview & Strategy - Migration capabilities overview
• Utility Operations - Stateless operations guide
• Error Reference - one page per failure type URI, with what to change
• Core API Endpoints^* - Complete API reference

The step-by-step import guide and the troubleshooting decision matrices are delivered with a licensed deployment rather than published here; ask whoever operates your deployment for either.

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