API Reference

Overview of the Cipherion Encryption API — authentication, base URL, response structure, and error codes

Overview

The Cipherion API provides server-side encryption and decryption services for strings and nested JSON objects. All cryptographic operations are project-scoped and authenticated via API key.

The API exposes four core endpoints:

Endpoint	Method	Description
`/encrypt/:projectId`	POST	Encrypt a plain text string
`/decrypt/:projectId`	POST	Decrypt an encrypted string back to plain text
`/deep_encrypt/:projectId`	POST	Recursively encrypt all fields in a nested JSON object
`/deep_decrypt/:projectId`	POST	Recursively decrypt all fields in a nested JSON object

Base URL

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

Authentication

Every request must include two pieces of identification: an API key passed as a header, and a project ID passed as a URL path parameter.

Required Header

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

URL Path Parameter

/:projectId

Your projectId is the project identifier from the Cipherion dashboard. It is appended directly to the endpoint path — for example:

POST /encrypt/proj_abc123

Never expose your API key, Project ID, or passphrase in client-side code or public repositories. Store all three in environment variables and access them server-side only.

Passphrase

All encrypt and decrypt operations require a passphrase. This is the passphrase you configured for your project in the Cipherion dashboard.

The passphrase you configured configured for your project in the Cipherion dashboard must be the same for the cryptographic operations. If the two do not match, the operation will fail with a 400 error.

Store your projectId, API key, and passphrase in environment variables. Never hardcode them in your application code or commit them to a repository.

CIPHERION_PROJECT_ID=your_project_id
CIPHERION_API_KEY=your_api_key
CIPHERION_PASSPHRASE=your_passphrase

If your database is breached, change your passphrase immediately in the Cipherion dashboard and update the environment variable in your application. Rotate your passphrase every month as a standard security practice.

Encrypted Package Format

All encrypted values produced by this API share a common three-part format:

[hash],[encrypted_data],[validation_token]

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

Never attempt to parse, modify, or construct encrypted packages manually. Always pass them back to the /decrypt or /deep_decrypt endpoints as-is.

Response Structure

All API responses — success and error alike — follow a consistent envelope:

{
  success: boolean;          // true on success, false on error
  statusCode: number;        // mirrors the HTTP status code
  message: string;           // human-readable status or error description
  data: object | null;       // response payload; null on error
  error?: {
    statusCode: number;
    isOperational: boolean | string;
  };
  timestamp: string;         // ISO 8601 — e.g. "2025-12-24T06:05:35.591Z"
}

Success Payload Fields

For /encrypt:

{
  "data": {
    "encrypted_output": "a2c8d832ab....Encrypted Package"
  }
}

For /decrypt:

{
  "data": {
    "plaintext": "your original string"
  }
}

For /deep_encrypt:

{
  "data": {
    "encrypted": {
      /* same structure as input, all leaf values encrypted */
    },
    "meta": {
      "excluded_fields": [],
      "excluded_patterns": [],
      "operation": "deep_encrypt"
    }
  }
}

For /deep_decrypt:

{
  "data": {
    "data": {
      /* same structure as input, all leaf values decrypted */
    },
    // Optional only for `/deep_encrypt` and `/deep_decrypt` endpoints
    "meta": {
        "excluded_fields": [],
        "excluded_patterns": [],
        "failed_fields": [],
        "fail_gracefully": boolean,
        "operation": "deep_encrypt" | "deep_decrypt"
    }
  }
}

Standard Error Responses

These error responses are common across all four endpoints.

400 Bad Request — Missing Fields

Returned when required fields (projectId, x-api-key, data/encrypted, or passphrase) are absent.

{
  "success": false,
  "statusCode": 400,
  "message": "Missing required fields: projectId, x-api-key header, data, or passphrase",
  "data": null,
  "timestamp": "2026-05-29T00:00:00.000Z"
}

400 Bad Request — Invalid Passphrase or Corrupted Data

Returned when the passphrase does not match the one used during encryption, or the encrypted package is malformed.

{
  "success": false,
  "statusCode": 400,
  "message": "Failed to unwrap AES key: possible invalid passphrase or corrupted data.",
  "data": null,
  "error": {
    "statusCode": 400,
    "isOperational": true
  },
  "timestamp": "2026-05-29T10:45:31.055Z"
}

401 Unauthorized — Invalid Credentials

Returned when the x-api-key header or projectId path parameter is invalid.

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid project or API key",
  "data": null,
  "error": {
    "statusCode": 401,
    "isOperational": true
  },
  "timestamp": "2026-05-29T00:00:00.000Z"
}

403 When API Key Does not Belong to the Project

Returned when the x-api-key header or projectId parameter does not belong to each other.

{
  "success": false,
  "statusCode": 403,
  "message": "API key does not belong to the specific project",
  "data": null,
  "error": null,
  "timestamp": "2026-05-29T10:46:50.496Z"
}

413 Payload Too Large — Field Limit Exceeded

Returned when the request contains more than 10,000 fields.

{
  "success": false,
  "statusCode": 413,
  "message": "Payload too large: maximum 10000 fields allowed per request (received X).",
  "data": null,
  "timestamp": "2026-05-29T00:00:00.000Z"
}

422 Unprocessable Entity — Plan Field Limit Exceeded

Returned when the request exceeds the field limit defined by your plan and overage is not enabled.

{
  "success": false,
  "statusCode": 422,
  "message": "Field limit exceeded: your plan allows a maximum of X fields per request...",
  "data": null,
  "timestamp": "2026-05-29T00:00:00.000Z"
}

429 Too Many Requests — Quota Exceeded

Returned when your plan's call quota for the billing period has been exhausted and overage is not enabled.

{
  "success": false,
  "statusCode": 429,
  "message": "encryption quota exceeded: your plan includes X calls per billing period...",
  "data": null,
  "timestamp": "2026-05-29T00:00:00.000Z"
}

500 Internal Server Error

Returned when an unexpected server-side error occurs.

{
  "success": false,
  "statusCode": 500,
  "message": "Encryption failed",
  "data": null,
  "error": {},
  "timestamp": "2026-05-29T00:00:00.000Z"
}

Status Code Summary

Code	Name	Common Causes
`200`	OK	Request processed successfully
`400`	Bad Request	Invalid passphrase, corrupted data, missing fields
`401`	Unauthorized	Invalid project ID or API key
`403`	Invalid	API Key does not belong Project
`413`	Payload Too Large	More than 10,000 fields in the request
`422`	Unprocessable Entity	Plan field limit exceeded, overage disabled
`429`	Too Many Requests	Billing period quota exhausted, overage disabled
`500`	Internal Server Error	Unexpected server-side failure

Rate Limits

Rate limits are enforced per project and API key. Contact support for your specific limits and enterprise quota options.

Support

Channel	Details
Email	official@cipherion.in
Documentation	https://docs.cipherion.in

API Reference

On this page