Skip to content

Testing the AnkaSecure API via Swagger UI

This page explains how to authenticate and test your Key Management, Secure, and Streaming endpoints directly from the interactive Swagger UI at /swagger-encryption/.

1) Open the Swagger UI

Navigate to: /swagger-encryption/ in your browser

(Depending on your deployment, you might also reach the same interface at /swagger-encryption/ or a similar route, but /swagger-ui/index.html is the standard.)

You should see a list of API tags, including:

  • Authentication

  • Key Management

  • Secure (non-streaming)

  • Secure Streaming

  • License Management

Each section expands to show the available endpoints.

2) Authenticate to Obtain a JWT Token

2.1 Application-Based Authentication

If you want to authenticate using clientId and clientSecret (for example, machine-to-machine scenarios):

  1. Scroll to the Authentication tag.

  2. Find POST /api/authenticate/app.

  3. Click Try it out, then expand the request body.

  4. Enter valid clientId and clientSecret in JSON, for example:

{
  "clientId": "allApp",
  "clientSecret": "demoAppPass!"
}

  1. Click Execute.

  2. If successful, you'll see a 200 response containing "token" and "refreshToken". Copy the "token" value.

2.2 User-Based Authentication

If you prefer user credentials:

  1. Still under Authentication, find POST /api/authenticate/login.

  2. Click Try it out, expand the JSON body, and provide a username and password:

{
  "username": "[email protected]",
  "password": "Password123!"
}

  1. Click Execute.

  2. On success, a 200 response returns "token" and "refreshToken". Copy the "token".

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGxBcHAiLCJyb2xlIjoiQVBQTElDQVRJT04iLCJzY29wZXMiOlsic3RyZWFtLnZlcmlmeVNpZ25hdHVyZVN0cmVhbSIsImtleV9tYW5hZ2VtZW50LnZpZXdTdXBwb3J0ZWRBbGdvcml0aG1zIiwic3RyZWFtLnNpZ25TdHJlYW0iLCJrZXlfbWFuYWdlbWVudC5yZXZva2VLZXkiLCJzZWN1cmUudmVyaWZ5U2lnbmF0dXJlIiwia2V5X21hbmFnZW1lbnQuZXhwb3J0S2V5Iiwia2V5X21hbmFnZW1lbnQuaW1wb3J0UHJpdmF0ZUtleVBrY3MxMiIsImtleV9tYW5hZ2VtZW50LmltcG9ydEtleSIsInNlY3VyZS5zaWduIiwibGljZW5zZU1hbmFnZW1lbnQuZ2V0TGljZW5zZUluZm8iLCJzZWN1cmUuZGVjcnlwdCIsInN0cmVhbS5lbmNyeXB0U3RyZWFtIiwia2V5X21hbmFnZW1lbnQuZ2VuZXJhdGVLZXkiLCJzdHJlYW0udmVyaWZ5U2lnbmF0dXJlVXRpbGl0eVN0cmVhbSIsInNlY3VyZS5lbmNyeXB0Iiwic2VjdXJlLnJlc2lnbiIsInN0cmVhbS5kZWNyeXB0U3RyZWFtIiwic2VjdXJlLnJlZW5jcnlwdCIsImtleV9tYW5hZ2VtZW50Lmxpc3RLZXlzIiwic3RyZWFtLnJlc2lnblN0cmVhbSIsInN0cmVhbS5yZWVuY3J5cHRTdHJlYW0iLCJrZXlfbWFuYWdlbWVudC5yZW1vdmVLZXkiLCJzdHJlYW0uZW5jcnlwdFV0aWxpdHlTdHJlYW0iXSwidHlwZSI6ImFjY2VzcyIsInVzZXJUeXBlIjoiQVBQTElDQVRJT04iLCJpYXQiOjE3NDIxNzY4NjksImV4cCI6MTc0MjUzNjg2OX0.Ch5ETtDGkrMD_0ocaI16QHor2vsQuogBZJSW4ZNoNYI",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGxBcHAiLCJyb2xlIjoiQVBQTElDQVRJT04iLCJzY29wZXMiOlsic3RyZWFtLnZlcmlmeVNpZ25hdHVyZVN0cmVhbSIsImtleV9tYW5hZ2VtZW50LnZpZXdTdXBwb3J0ZWRBbGdvcml0aG1zIiwic3RyZWFtLnNpZ25TdHJlYW0iLCJrZXlfbWFuYWdlbWVudC5yZXZva2VLZXkiLCJzZWN1cmUudmVyaWZ5U2lnbmF0dXJlIiwia2V5X21hbmFnZW1lbnQuZXhwb3J0S2V5Iiwia2V5X21hbmFnZW1lbnQuaW1wb3J0UHJpdmF0ZUtleVBrY3MxMiIsImtleV9tYW5hZ2VtZW50LmltcG9ydEtleSIsInNlY3VyZS5zaWduIiwibGljZW5zZU1hbmFnZW1lbnQuZ2V0TGljZW5zZUluZm8iLCJzZWN1cmUuZGVjcnlwdCIsInN0cmVhbS5lbmNyeXB0U3RyZWFtIiwia2V5X21hbmFnZW1lbnQuZ2VuZXJhdGVLZXkiLCJzdHJlYW0udmVyaWZ5U2lnbmF0dXJlVXRpbGl0eVN0cmVhbSIsInNlY3VyZS5lbmNyeXB0Iiwic2VjdXJlLnJlc2lnbiIsInN0cmVhbS5kZWNyeXB0U3RyZWFtIiwic2VjdXJlLnJlZW5jcnlwdCIsImtleV9tYW5hZ2VtZW50Lmxpc3RLZXlzIiwic3RyZWFtLnJlc2lnblN0cmVhbSIsInN0cmVhbS5yZWVuY3J5cHRTdHJlYW0iLCJrZXlfbWFuYWdlbWVudC5yZW1vdmVLZXkiLCJzdHJlYW0uZW5jcnlwdFV0aWxpdHlTdHJlYW0iXSwidHlwZSI6InJlZnJlc2giLCJ1c2VyVHlwZSI6IkFQUExJQ0FUSU9OIiwiaWF0IjoxNzQyMTc2ODY5LCJleHAiOjE3NDI4OTY4Njl9.mVitkdn4tZU60qyFub0qauadE2I4HWY6ldovPcMHI8w"
}

Note: You can also call POST /api/authenticate/refresh later to exchange your "refreshToken" for a new Access Token without re-entering credentials.

3) Authorize with Your JWT Token

At the top-right corner of the Swagger UI, there's an Authorize button (often shown as a green lock).

  1. Click Authorize.

  2. A pop-up appears, typically titled "Available Authorizations."

  3. In the bearerAuth or similar field, paste your token, prefixed with Bearer if required.

    • For example:

    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

  4. Click Authorize, then Close.

Swagger UI now automatically includes your JWT in the Authorization header for subsequent requests, allowing access to secured endpoints.

Tip: If your token expires, repeat this step with a fresh token.

4) Test Key Management Endpoints

With a valid token, you can explore the Key Management category. Some commonly used operations include:

  • GET /api/key-management/supported-algorithms

    Retrieves all dynamically supported algorithms (kty + alg). For example, "ML-KEM-768", "RSA-2048", or "AES-256".

  • POST /api/key-management/keys

    Generates a new cryptographic key, either classical (RSA/ECC), symmetric (AES), or post-quantum (e.g. ML-KEM). Example request body:

{
  "kid": "myNewKey",
  "kty": "ML-KEM",
  "alg": "ML-KEM-768",
  "exportable": true
}

  • GET /api/key-management/keys

    Lists all existing keys (public metadata only).

  • GET /api/key-management/keys/{kid}

    Exports a key by kid, returning JSON with publicKey for asymmetric keys and usage details.

  • POST /api/key-management/keys/import

    Imports an existing key (public or private), including PQC or classical. Example:

{
  "kid": "importedKey",
  "kty": "RSA",
  "alg": "RSA-2048",
  "publicKey": "BASE64-PUBLIC",
  "privateKey": "BASE64-PRIVATE"
}

  • POST /api/key-management/private-keys

    Imports a private key from a PKCS#12 file (Base64-encoded .p12 content).

  • POST /api/key-management/keys/{kid}/revoke

    Revokes a key by setting its status to REVOKED.

  • DELETE /api/key-management/keys/{kid}

    Removes a key entirely (irreversible).

5) Test Secure (Non-Streaming) Endpoints

Under the Secure category, you'll see classical cryptographic operations:

  • POST /api/crypto/encrypt

    Encrypts Base64-encoded data using the public key of the specified key (kid).

  • POST /api/crypto/decrypt

    Decrypts Base64-encoded data using the private key of the specified key (kid).

  • POST /api/crypto/sign

    Signs Base64-encoded data with a private key. Returns a Base64 signature.

  • POST /api/crypto/verify

    Verifies a signature for Base64-encoded data using a public key.

  • POST /api/crypto/reencrypt

    Re-encrypts data from oldKid (private) to newKid (public).

  • POST /api/crypto/resign

    Re-signs data by verifying with oldKid (public) and signing again with newKid (private).

How to test:

  1. Click Try it out.

  2. Provide the JSON body with the appropriate fields (e.g., kid, data, etc.).

  3. Click Execute.

  4. Check the response for the resulting Base64 encryption/signature or verification status.

6) Test Secure Streaming Endpoints

The Secure Streaming category uses multipart/form-data for large files or streaming scenarios:

  • POST /api/crypto/stream/encrypt

    Expects JSON metadata (kid=public key) plus a file part for the plaintext, returning the ciphertext as a streaming response.

  • POST /api/crypto/stream/decrypt

    Expects JSON metadata (kid=private key) plus a file part for the ciphertext, returning the plaintext as a streaming response.

  • POST /api/crypto/stream/sign

    Sends a file and JSON metadata (kid=private key) to sign the file contents, returning the signature bytes.

  • POST /api/crypto/stream/verify

    Sends a file and JSON metadata (kid=public key + signatureBase64) to verify the signature.

  • POST /api/crypto/stream/reencrypt

    Streams data from oldKid (private) to newKid (public).

  • POST /api/crypto/stream/resign

    Verifies old signature with oldKid (public) and re-signs with newKid (private).

Using Swagger UI for large file uploads in streaming endpoints can be less intuitive since you must upload a file through the "multipart/form-data" interface. However, you can still test with small sample files. For truly large data, a CLI or custom script might be easier.

7) (Optional) Test Utility Endpoints for Public-Key (Ephemeral) Operations

The Secure Streaming tag also includes "utility" endpoints that let you encrypt or verify a file without referencing a stored key:

  • POST /api/crypto/stream/utility/publickey-encrypt

    Provide a JSON part with .alg, .publicKey (Base64), and a file part to encrypt.

  • POST /api/crypto/stream/utility/publickey-verify

    Provide a JSON part with .alg, .publicKey, .signatureBase64 plus a file. The API verifies the signature on the provided file, not storing the key in the keystore.

These operations do not require a kid but do require you to supply the entire public key in Base64/PEM.

8) License Management

If your API requires checking or displaying license details, see the License Management tag:

  • GET /api/license-management/license-info/{clientId}

    Retrieves license info for the specified clientId (plan type, expiry date, usage stats, etc.).

You may need to authenticate first (via bearerAuth), unless your deployment allows public license queries.

9) Wrapping Up

  • Re-Authorize if Token Expires: If you see a 401 (Unauthorized) at any point, your JWT token may have expired. You can get a new Access Token via POST /api/authenticate/refresh (if you have a Refresh Token) or repeat the login/app-auth step.

  • File-based (Multipart) Testing: For large file scenarios, consider the CLI or your own scripts to handle streaming and to get progress indicators. Swagger UI supports multipart uploads but is more convenient for small test files.

  • Error Handling: Check the returned HTTP status and see if the response body includes an ErrorResponse with fields like status, error, message, path, and timestamp.

Quick Reference:

  • Authentication: POST /api/authenticate/app or POST /api/authenticate/login

  • Key Management: Generate, import, list, export, remove, revoke, or retrieve supported algorithms.

  • Secure (non-streaming): Encrypt/decrypt, sign/verify, re-encrypt, re-sign with Base64 data.

  • Secure Streaming: Multipart endpoints for large file encryption, decryption, signing, verification, re-encrypt, re-sign.

  • License Management: /api/license-management/license-info/{clientId} to check plan status, usage, etc.

With these steps, you should be able to test all major operations of the AnkaSecure API directly from Swagger UI. For advanced use cases (like large files or automation), the CLI or custom scripts can help. Enjoy exploring and verifying your cryptographic operations!