Cipherion

API Reference

Complete API reference for Cipherion encryption and decryption endpoints

Base URL

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

Authentication

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

Required Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

URL Parameters

  • projectId - Your project identifier (passed as a path parameter)

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

Encrypt Data

Encrypts plain text data or normal String.

Endpoint

POST /encrypt/:projectId

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

Request Body

ParameterTypeRequiredDescription
datastringYesPlain text or a String data to encrypt
passphrasestringYesPassphrase for encryption

Example Request

Method: POST
URL: https://api.cipherion.in/api/v1/crypto/encrypt/YOUR_PROJECT_ID

Headers:
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body (raw JSON):
{
  "data": "sensitive information to encrypt",
  "passphrase": "your-secure-passphrase"
}
{
  "data": "sensitive information to encrypt",
  "passphrase": "your-secure-passphrase"
}
curl -X POST https://api.cipherion.in/api/v1/crypto/encrypt/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "sensitive information to encrypt",
    "passphrase": "your-secure-passphrase"
  }'

Success Response

Status Code: 200 OK

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

Error Responses

401 Unauthorized - Invalid credentials

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

400 Bad Request - Invalid passphrase or corrupted data

{
  "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.

Endpoint

POST /decrypt/:projectId

Request Body

ParameterTypeRequiredDescription
datastringYesEncrypted data package to decrypt
passphrasestringYesOriginal passphrase used for encryption

Example Request

Method: POST
URL: https://api.cipherion.in/api/v1/crypto/decrypt/YOUR_PROJECT_ID

Headers:
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body (raw JSON):
{
  "data": "a2c8d832ab28c....Encrypted Package",
  "passphrase": "your-secure-passphrase"
}
{
  "data": "a2c8d832ab28c....Encrypted Package",
  "passphrase": "your-secure-passphrase"
}
curl -X POST https://api.cipherion.in/api/v1/crypto/decrypt/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "a2c8d832ab28c....Encrypted Package",
    "passphrase": "your-secure-passphrase"
  }'

Success Response

Status Code: 200 OK

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

Error Responses

400 Bad Request - Corrupted package

{
  "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 optional field exclusions. This endpoint is ideal for encrypting complex data structures while preserving certain fields in plaintext.

Endpoint

POST /deep_encrypt/:projectId

Request Body

ParameterTypeRequiredDescription
dataobjectYesJSON object to encrypt recursively
passphrasestringYesSecure passphrase for encryption
exclude_fieldsarrayNoSpecific field paths to exclude (e.g., ["orders[0].items[0].name"])
exclude_patternsarrayNoPattern-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.

Basic Example

Method: POST
URL: https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID

Headers:
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body (raw JSON):
{
  "data": {
    "name": "John Doe",
    "user_id": "12345"
  },
  "passphrase": "your-secure-passphrase"
}
{
  "data": {
    "name": "John Doe",
    "user_id": "12345"
  },
  "passphrase": "your-secure-passphrase"
}
curl -X POST https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "John Doe",
      "user_id": "12345"
    },
    "passphrase": "your-secure-passphrase"
  }'

Advanced Example with Exclusions

Method: POST
URL: https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID

Headers:
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body (raw JSON):
{
  "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",
      "address": {
        "street": "123 Tech Blvd",
        "city": "Cyberdyne"
      }
    }
  },
  "passphrase": "your-secure-passphrase",
  "exclude_patterns": ["user_id", "*_at", "timestamp"]
}
{
  "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",
      "address": {
        "street": "123 Tech Blvd",
        "city": "Cyberdyne"
      }
    }
  },
  "passphrase": "your-secure-passphrase",
  "exclude_patterns": ["user_id", "*_at", "timestamp"]
}
curl -X POST https://api.cipherion.in/api/v1/crypto/deep_encrypt/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
        "address": {
          "street": "123 Tech Blvd",
          "city": "Cyberdyne"
        }
      }
    },
    "passphrase": "your-secure-passphrase",
    "exclude_patterns": ["user_id", "*_at", "timestamp"]
  }'

Success Response

Status Code: 200 OK

{
  "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",
        "address": {
          "street": "54511b48cf....Encrypted Package",
          "city": "de02e1b0e5f....Encrypted Package"
        }
      }
    },
    "meta": {
        "excluded_fields": [],
        "excluded_patterns": ["user_id", "*_at", "timestamp"],
        "operation": "deep_encrypt"
      },
    }
  },
  "timestamp": "2025-12-24T06:36:29.586Z"
}

Error Responses

401 Unauthorized - Invalid credentials

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

400 Bad Request - Invalid passphrase or corrupted data

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

Fields matching exclude_patterns remain in plaintext. The meta object provides details about the encryption operation including cost and field counts.

Pattern Matching

The exclude_patterns parameter supports wildcard matching:

  • *_at matches created_at, updated_at, etc.
  • user_id matches exact field name
  • Patterns are case-sensitive

Specific Field Exclusions

Use array notation for nested field paths in exclude_fields:

{
  "exclude_fields": ["orders[0].items[0].name", "orders[0].items[1].price"]
}

Deep Decrypt

Recursively decrypts nested JSON objects with optional field exclusions and graceful failure handling.

Endpoint

POST /deep_decrypt/:projectId

Request Body

ParameterTypeRequiredDescription
encryptedobjectYesEncrypted JSON object to decrypt recursively
passphrasestringYesOriginal passphrase used for encryption
exclude_fieldsarrayNoSpecific field paths to skip during decryption
exclude_patternsarrayNoPattern-based exclusions
fail_gracefullybooleanNoContinue decryption on errors (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

Basic Example

Method: POST
URL: https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID

Headers:
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body (raw JSON):
{
  "encrypted": {
    "name": "a3f8d9e2c1....Encrypted Package",
    "user_id": "b2c9e1f3a4d....Encrypted Package"
  },
  "passphrase": "your-secure-passphrase"
}
{
  "encrypted": {
    "name": "a3f8d9e2c1....Encrypted Package",
    "user_id": "b2c9e1f3a4d....Encrypted Package"
  },
  "passphrase": "your-secure-passphrase"
}
curl -X POST https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted": {
      "name": "a3f8d9e2c1....Encrypted Package",
      "user_id": "b2c9e1f3a4d....Encrypted Package"
    },
    "passphrase": "your-secure-passphrase"
  }'

Advanced Example with Graceful Failure

Method: POST
URL: https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID

Headers:
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body (raw JSON):
{
  "encrypted": {
    "orders": [{
      "order_id": "ORD-1",
      "items": [{
        "product_id": "P1",
        "name": "351b4c79d0....Encrypted Package",
        "price": "c0e93b516997....Encrypted Package"
      }]
    }]
  },
  "passphrase": "your-secure-passphrase",
  "exclude_fields": ["orders[0].items[0].name"],
  "exclude_patterns": ["order_id", "product_id"],
  "fail_gracefully": true
}
{
  "encrypted": {
    "orders": [{
      "order_id": "ORD-1",
      "items": [{
        "product_id": "P1",
        "name": "351b4c79d0....Encrypted Package",
        "price": "c0e93b516997....Encrypted Package"
      }]
    }]
  },
  "passphrase": "your-secure-passphrase",
  "exclude_fields": ["orders[0].items[0].name"],
  "exclude_patterns": ["order_id", "product_id"],
  "fail_gracefully": true
}
curl -X POST https://api.cipherion.in/api/v1/crypto/deep_decrypt/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted": {
      "orders": [{
        "order_id": "ORD-1",
        "items": [{
          "product_id": "P1",
          "name": "351b4c79d0....Encrypted Package",
          "price": "c0e93b516997....Encrypted Package"
        }]
      }]
    },
    "passphrase": "your-secure-passphrase",
    "exclude_fields": ["orders[0].items[0].name"],
    "exclude_patterns": ["order_id", "product_id"],
    "fail_gracefully": true
  }'

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.

Success Response

Status Code: 200 OK

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

Success Response with Failed Fields

When fail_gracefully is enabled, failed decryptions are tracked but don't stop the process:

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

Error Response (Non-Graceful Mode)

400 Bad Request - Decryption failure

{
  "success": false,
  "statusCode": 400,
  "message": "Failed to decrypt field: possible invalid passphrase or corrupted data",
  "data": null,
  "error": {
    "statusCode": 400,
    "isOperational": "Failed to decrypt field: possible invalid passphrase or corrupted data"
  },
  "timestamp": "2025-12-24T06:51:34.399Z"
}

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 consistent structure:

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

Success Response Data Fields

Encrypt/Decrypt Operations:

  • encrypted_output - Encrypted data package
  • plaintext - Decrypted plain text

Deep Encrypt/Decrypt Operations:

  • encrypted or data - Processed JSON object
  • meta - Operation metadata including:
    • encryptionMetadata or decryptedMetadata - Configuration used
    • totalFields - Total number of fields processed
    • billableFields - Number of fields that incurred charges
    • totalPrice - Cost of the operation
    • failed_fields - Array of fields that failed (deep_decrypt only)

Status Codes

Status CodeDescriptionCommon Causes
200SuccessRequest processed successfully
400Bad RequestInvalid passphrase, corrupted data, malformed request
401UnauthorizedInvalid project ID or API key

Best Practices

Security

  • Store API keys securely using environment variables
  • Use strong, unique passphrases for encryption
  • Rotate passphrases periodically
  • Never log or expose encrypted data packages

Periodically change or revoke the passphrase for enhanced security.

Performance

  • Use deep encryption for complex nested objects
  • Leverage exclude_patterns for non-sensitive data
  • Enable fail_gracefully for partial decryption scenarios

Rate Limits

Rate limits are enforced per project and API key. Contact support for specific rate limit information and enterprise quotas.

Support

For technical support, API access, or billing inquiries:

Changing Passphrase

Securely update your master passphrase and migrate existing encrypted data to use the new passphrase.

API Reference for Node.js

Complete API reference for Cipherion Crypto API with authentication, endpoints, and examples for Node.js

On this page

Base URLAuthenticationRequired HeadersURL ParametersEncrypt DataEndpointRequest BodyExample RequestSuccess ResponseError ResponsesDecrypt DataEndpointRequest BodyExample RequestSuccess ResponseError ResponsesDeep EncryptEndpointRequest BodyBasic ExampleAdvanced Example with ExclusionsSuccess ResponseError ResponsesPattern MatchingSpecific Field ExclusionsDeep DecryptEndpointRequest BodyBasic ExampleAdvanced Example with Graceful FailureSuccess ResponseSuccess Response with Failed FieldsError Response (Non-Graceful Mode)Encrypted Package FormatResponse StructureSuccess Response Data FieldsStatus CodesBest PracticesSecurityPerformanceRate LimitsSupport