API Reference for Java

Complete API reference for Cipherion Crypto API with authentication, endpoints, and examples for Java

Base URL

https://api.cipherion.in/api/v1/crypto

Authentication

All API requests require authentication using an API key and project identifier.

Headers

Header	Description
`x-api-key`	Your API key

URL Parameters

Parameter	Description
`projectId`	Your project identifier (passed as path parameter)

Keep your API key and Project Id secure and never expose them in client-side code or public repositories.

Endpoints

Encrypt Data

Encrypts text data or normal String.

POST /encrypt/:projectId

Use the passphrase which is used to create the encryption key in Cipherion's dashboard.

Request Body

Field	Type	Required	Description
`data`	string	Yes	Plain text or a String data to encrypt
`passphrase`	string	Yes	Passphrase for encryption

Example Request

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import org.json.JSONObject;

public class CipherionExample {
    public static void main(String[] args) throws Exception {
        String url = "https://api.cipherion.in/api/v1/crypto/encrypt/YOUR_PROJECT_ID";

        JSONObject payload = new JSONObject();
        payload.put("data", "Hello");
        payload.put("passphrase", "YOUR_SECURE_PASSPHRASE");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Data encrypted successfully",
  "data": {
    "encrypted_output": "a2c8d832ab....Encrypted Package"
  },
  "timestamp": "2025-12-24T06:05:35.591Z"
}

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid project or API key",
  "data": null,
  "error": {
    "statusCode": 401,
    "isOperational": true
  },
  "timestamp": "2025-12-24T06:18:26.585Z"
}

{
  "success": false,
  "statusCode": 400,
  "message": "Failed to unwrap AES key: possible invalid passphrase or corrupted data",
  "data": null,
  "error": {
    "statusCode": 400,
    "isOperational": "Failed to unwrap AES key: possible invalid passphrase or corrupted data"
  },
  "timestamp": "2025-12-24T06:19:16.669Z"
}

Decrypt Data

Decrypts encrypted data using the original passphrase.

POST /decrypt/:projectId

Request Body

Field	Type	Required	Description
`data`	string	Yes	Encrypted data package
`passphrase`	string	Yes	Original passphrase used for encryption

Example Request

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import org.json.JSONObject;

public class CipherionDecrypt {
    public static void main(String[] args) throws Exception {
        String url = "https://api.cipherion.in/api/v1/crypto/decrypt/YOUR_PROJECT_ID";

        JSONObject payload = new JSONObject();
        payload.put("data", "a2c8d832ab28c....Encrypted Package");
        payload.put("passphrase", "YOUR_SECURE_PASSPHRASE");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Data decrypted successfully",
  "data": {
    "plaintext": "Hello"
  },
  "timestamp": "2025-12-24T06:20:46.618Z"
}

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid project or API key",
  "data": null,
  "error": {
    "statusCode": 401,
    "isOperational": true
  },
  "timestamp": "2025-12-24T06:21:42.450Z"
}

{
  "success": false,
  "statusCode": 400,
  "message": "Encrypted package is corrupted or malformed.",
  "data": null,
  "error": {
    "statusCode": 400,
    "isOperational": "Encrypted package is corrupted or malformed."
  },
  "timestamp": "2025-12-24T06:22:04.208Z"
}

Deep Encrypt

Recursively encrypts nested JSON objects with granular control over field exclusions.

POST /deep_encrypt/:projectId

Request Body

Field	Type	Required	Description
`data`	object	Yes	JSON object to encrypt
`passphrase`	string	Yes	Secure passphrase for encryption
`exclude_fields`	array	No	Specific field paths to exclude (e.g., `["orders[0].items[0].name"]`)
`exclude_patterns`	array	No	Pattern-based exclusions supporting wildcards (e.g., `["user_id", "*_at"]`)

Pattern matching supports wildcards. For example, *_at will match created_at, updated_at, and any field ending with _at.

Example Request - Basic

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import org.json.JSONObject;

public class CipherionDeepEncrypt {
    public static void main(String[] args) throws Exception {
        String url = "https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID";

        JSONObject data = new JSONObject();
        data.put("name", "John Doe");
        data.put("user_id", "user_123");

        JSONObject payload = new JSONObject();
        payload.put("data", data);
        payload.put("passphrase", "YOUR_SECURE_PASSPHRASE");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Example Request - With Exclusions

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import org.json.JSONObject;
import org.json.JSONArray;

public class CipherionDeepEncryptExclusions {
    public static void main(String[] args) throws Exception {
        String url = "https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID";

        JSONObject personalInfo = new JSONObject();
        personalInfo.put("full_name", "Sarah Connor");
        personalInfo.put("ssn", "999-00-1234");

        JSONObject data = new JSONObject();
        data.put("user_id", "u_99283");
        data.put("created_at", "2025-10-24T10:00:00Z");
        data.put("updated_at", "2025-10-25T11:30:00Z");
        data.put("personal_info", personalInfo);

        JSONArray excludePatterns = new JSONArray();
        excludePatterns.put("user_id");
        excludePatterns.put("*_at");

        JSONObject payload = new JSONObject();
        payload.put("data", data);
        payload.put("passphrase", "YOUR_SECURE_PASSPHRASE");
        payload.put("exclude_patterns", excludePatterns);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Payload encrypted successfully",
  "data": {
    "encrypted": {
      "user_id": "u_99283",
      "created_at": "2025-10-24T10:00:00Z",
      "updated_at": "2025-10-25T11:30:00Z",
      "personal_info": {
        "full_name": "5882eeda72....Encrypted Package",
        "ssn": "c035c619cf....Encrypted Package"
      }
    },
    "meta": {
      "excluded_fields": [],
      "excluded_patterns": ["user_id", "*_at"],
      "operation": "deep_encrypt"
    }
  },
  "timestamp": "2025-12-24T06:36:29.586Z"
}

Deep Decrypt

Recursively decrypts nested JSON objects with optional graceful failure handling.

POST /deep_decrypt/:projectId

Request Body

Field	Type	Required	Description
`encrypted`	object	Yes	Encrypted JSON object
`passphrase`	string	Yes	Original passphrase used for encryption
`exclude_fields`	array	No	Specific field paths to exclude from decryption
`exclude_patterns`	array	No	Pattern-based exclusions
`fail_gracefully`	boolean	No	Continue decryption even if some fields fail (default: true)

When fail_gracefully is set to false, the decryption process fails immediately if any field cannot be decrypted.

Set fail_gracefully to true in the following scenarios:

When the payload contains unencrypted fields
When the encrypted data is corrupted or partially malformed

Example Request

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import org.json.JSONObject;

public class CipherionDeepDecrypt {
    public static void main(String[] args) throws Exception {
        String url = "https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID";

        JSONObject encrypted = new JSONObject();
        encrypted.put("name", "a3f8d9e2c1....Encrypted Package");
        encrypted.put("user_id", "b2c9e1f3a4d....Encrypted Package");

        JSONObject payload = new JSONObject();
        payload.put("encrypted", encrypted);
        payload.put("passphrase", "YOUR_SECURE_PASSPHRASE");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Example Request - With Graceful Failure

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import org.json.JSONObject;
import org.json.JSONArray;

public class CipherionDeepDecryptGraceful {
    public static void main(String[] args) throws Exception {
        String url = "https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID";

        JSONObject item = new JSONObject();
        item.put("name", "351b4c79d0....Encrypted Package");
        item.put("price", "c0e93b516997....Encrypted Package");

        JSONArray items = new JSONArray();
        items.put(item);

        JSONObject order = new JSONObject();
        order.put("order_id", "ORD-1");
        order.put("items", items);

        JSONArray orders = new JSONArray();
        orders.put(order);

        JSONObject data = new JSONObject();
        data.put("orders", orders);

        JSONObject encrypted = new JSONObject();
        encrypted.put("data", data);

        JSONArray excludePatterns = new JSONArray();
        excludePatterns.put("order_id");

        JSONObject payload = new JSONObject();
        payload.put("encrypted", encrypted);
        payload.put("passphrase", "YOUR_SECURE_PASSPHRASE");
        payload.put("exclude_patterns", excludePatterns);
        payload.put("fail_gracefully", true);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

When fail_gracefully is true, fields that fail to decrypt remain in their encrypted form and are listed in failed_fields. Set to false to fail immediately on any error.

Response - Success

{
  "success": true,
  "statusCode": 200,
  "message": "Payload decrypted successfully",
  "data": {
    "data": {
      "name": "John Doe",
      "user_id": "user_123"
    },
    "meta": {
      "excluded_fields": [],
      "excluded_patterns": [],
      "failed_fields": [],
      "fail_gracefully": true,
      "operation": "deep_decrypt"
    }
  },
  "timestamp": "2025-12-24T06:13:08.120Z"
}

Response - With Failed Fields

{
  "success": true,
  "statusCode": 200,
  "message": "Payload decrypted successfully",
  "data": {
    "data": {
      "orders": [
        {
          "order_id": "ORD-1",
          "items": [
            {
              "name": "351b4c79d0....Encrypted Package",
              "price": "50"
            }
          ]
        }
      ]
    },
    "meta": {
      "excluded_fields": [],
      "excluded_patterns": ["order_id"],
      "failed_fields": ["data.orders[0].items[0].name"],
      "fail_gracefully": true,
      "operation": "deep_decrypt"
    }
  },
  "timestamp": "2025-12-24T06:50:19.554Z"
}

Encrypted Package Format

The encrypted output consists of three comma-separated components:

[hash],[encrypted_data],[validation_token]

hash - Cryptographic hash of the original data
encrypted_data - AES encrypted payload
validation_token - Integrity verification token

Do not attempt to parse or modify encrypted packages manually. Always use the decrypt endpoints to retrieve original data.

Response Structure

All API responses follow a standardized structure for consistency and ease of integration.

Base Response Format

{
  success: boolean;
  statusCode: number;
  message: string;
  data: object | null;
  error: object | null;
  timestamp: string; // ISO 8601 format
}

Metadata Object

Deep encryption and decryption operations include a meta object with detailed operation information.

{
    excluded_fields: string[];
    excluded_patterns: string[];
    operation: string;
    failed_fields?: string[]; // Only in deep_decrypt responses
}

Status Codes

Status Code	Description
`200`	Success - Request completed successfully
`400`	Bad Request - Invalid passphrase, corrupted data, or malformed request
`401`	Unauthorized - Invalid project ID or API key

Common Error Scenarios

Invalid Authentication

Occurs when the API key or project ID is incorrect.

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid project or API key",
  "data": null,
  "error": {
    "statusCode": 401,
    "isOperational": true
  },
  "timestamp": "2025-12-24T06:18:26.585Z"
}

Invalid Passphrase

Occurs when the passphrase used for decryption does not match the encryption passphrase.

{
  "success": false,
  "statusCode": 400,
  "message": "Failed to unwrap AES key: possible invalid passphrase or corrupted data",
  "data": null,
  "error": {
    "statusCode": 400,
    "isOperational": "Failed to unwrap AES key: possible invalid passphrase or corrupted data"
  },
  "timestamp": "2025-12-24T06:19:16.669Z"
}

Corrupted Data

Occurs when the encrypted package is malformed or corrupted.

{
  "success": false,
  "statusCode": 400,
  "message": "Encrypted package is corrupted or malformed.",
  "data": null,
  "error": {
    "statusCode": 400,
    "isOperational": "Encrypted package is corrupted or malformed."
  },
  "timestamp": "2025-12-24T06:22:04.208Z"
}

Best Practices

Security Considerations

Passphrase Management: Store passphrases securely using environment variables or secret management systems. Never hardcode passphrases in your application.
API Key Protection: Treat your API key as a sensitive credential. Rotate keys regularly and never expose them in client-side code.
HTTPS Only: All API requests must use HTTPS to ensure data transmission security.

Periodically change or revoke the passphrase for enhanced security.

Performance Optimization

Batch Operations: Use deep encryption/decryption for nested objects rather than making multiple individual requests.
Strategic Exclusions: Use exclude_patterns and exclude_fields to skip non-sensitive data, reducing processing time and costs.
Graceful Failure: Enable fail_gracefully in production environments to handle partial data corruption without complete request failure.

Field Exclusion Patterns

Array Notation

Use bracket notation for array elements:

orders[0].items[0].name

Wildcard Patterns

Use asterisks for pattern matching:

*_at    // Matches: created_at, updated_at, deleted_at
user_*  // Matches: user_id, user_name, user_email

Rate Limits

Rate limits are enforced per project and API key. Contact Cipherion support for information about rate limits and quotas for your specific plan.

Maven Dependencies

Add these dependencies to your pom.xml:

<dependencies>
    <!-- JSON Processing -->
    <dependency>
        <groupId>org.json</groupId>
        <artifactId>json</artifactId>
        <version>20231013</version>
    </dependency>
</dependencies>

Gradle Dependencies

Add these dependencies to your build.gradle:

dependencies {
    implementation 'org.json:json:20231013'
}

Support

For additional support, API questions, or feature requests:

Documentation: https://docs.cipherion.in
Email: official@cipherion.in
Status Page: https://status.cipherion.in

API Reference for Java

On this page