API Reference for Python

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

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 secure and never expose it in client-side code or public repositories.

Endpoints

Encrypt Data

Encrypts text data or normal String.

POST /encrypt/:projectId

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 requests

url = "https://api.cipherion.in/api/v1/crypto/encrypt/YOUR_PROJECT_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "data": "Hello",
    "passphrase": "YOUR_SECURE_PASSPHRASE"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

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 requests

url = "https://api.cipherion.in/api/v1/crypto/decrypt/YOUR_PROJECT_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "data": "a2c8d832ab28c....Encrypted Package",
    "passphrase": "YOUR_SECURE_PASSPHRASE"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

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 requests

url = "https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "data": {
        "name": "John Doe",
        "user_id": "user_123"
    },
    "passphrase": "YOUR_SECURE_PASSPHRASE"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Example Request - With Exclusions

import requests

url = "https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "data": {
        "user_id": "u_99283",
        "created_at": "2025-10-24T10:00:00Z",
        "updated_at": "2025-10-25T11:30:00Z",
        "personal_info": {
            "full_name": "Sarah Connor",
            "ssn": "999-00-1234"
        }
    },
    "passphrase": "YOUR_SECURE_PASSPHRASE",
    "exclude_patterns": ["user_id", "*_at"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

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 requests

url = "https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "encrypted": {
        "name": "a3f8d9e2c1....Encrypted Package",
        "user_id": "b2c9e1f3a4d....Encrypted Package"
    },
    "passphrase": "YOUR_SECURE_PASSPHRASE"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Example Request - With Graceful Failure

import requests

url = "https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "encrypted": {
        "data": {
            "orders": [{
                "order_id": "ORD-1",
                "items": [{
                    "name": "351b4c79d0....Encrypted Package",
                    "price": "c0e93b516997....Encrypted Package"
                }]
            }]
        }
    },
    "passphrase": "YOUR_SECURE_PASSPHRASE",
    "exclude_patterns": ["order_id"],
    "fail_gracefully": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

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"
}

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.

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

Contact Cipherion support for information about rate limits and quotas for your specific plan.

Support

For additional support, API questions, or feature requests:

Documentation: [https://docs.cipherion.in]
Email: official@cipherion.in

API Reference for Python

On this page