API Reference

Complete reference documentation for Cipherion's REST and gRPC APIs. Integrate secure encryption into your applications with ease.

API Overview

Cipherion provides both REST and gRPC APIs for maximum flexibility

REST API

HTTP-based API with JSON payloads, perfect for web applications and quick integrations.

Base URL: https://api.cipherion.com/v1

Rate Limit: 1000 requests/minute

gRPC API (Coming Soon...)

High-performance binary protocol for low-latency, high-throughput applications.

Endpoint: grpc.cipherion.com:443

Protocol: HTTP/2 with TLS

Authentication

All API requests require authentication using your API key

Authorization Header

Authorization: Bearer cph_live_sk_your_api_key_here

REST Example

curl -X POST 
https://api.cipherion.com/v1/encrypt\
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

gRPC Metadata

metadata = {
'authorization': 'Bearer YOUR_API_KEY'
}

API Endpoints

Encrypt DataPOST

Encrypt sensitive data using field-level encryption

Endpoint

POST /v1/encrypt

Request Body

{
  "data": "john.doe@example.com",
  "passphrase": "your-secure-passphrase"
  }
}

Response

{
  "success": true,
  "encrypted_data": "cph_enc_abc123def456...",
  "data_type": "email",
  "encryption_method": "field_level",
  "algorithm": "AES-256-GCM",
  "key_id": "derived_key_xyz789",
  "context": "user_email_field",
  "request_id": "req_987654321",
  "timestamp": "2024-01-15T10:30:00Z"
}

Parameters

Parameter	Type	Required	Description
`data`	string	✓	The sensitive data to encrypt
`data_type`	string	✓	Type of data (email, ssn, phone, etc.)
`passphrase`	string	✓	Master passphrase for key derivation
`context`	string		Additional context for key derivation
`format_preserving`	boolean		Preserve original data format

Deep EncryptPOST

Encrypt deeply nested objects using recursive field-level encryption

Endpoint

POST /v1/deep-encrypt

Request Body

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "address": {
        "line1": "123 Street",
        "zipcode": "123456"
      }
    },
    "transaction": {
      "amount": 1500,
      "card_number": "4111111111111111"
    }
  },
  "passphrase": "your-secure-passphrase"
}

Response

{
  "success": true,
  "encrypted_data": {
    "user": {
      "name": "cph_enc_xyz...",
      "email": "cph_enc_abc...",
      "address": {
        "line1": "cph_enc_123...",
        "zipcode": "cph_enc_456..."
      }
    },
    "transaction": {
      "amount": 1500,
      "card_number": "cph_enc_card..."
    }
  },
  "encryption_method": "deep_field_level",
  "algorithm": "AES-256-GCM",
  "request_id": "req_24861923",
  "timestamp": "2025-08-05T12:00:00Z"
}

Parameters

Parameter	Type	Required	Description
`data`	object	✓	Nested object containing fields to encrypt
`data_type`	string	✓	Type of data (email, ssn, phone, etc.)
`passphrase`	string	✓	Master passphrase for encryption key derivation
`context`	string		Optional context to scope encryption
`format_preserving`	boolean		Whether to retain original data format where possible

Error Handling

Understanding API error responses and status codes

Standard Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_PASSPHRASE",
    "message": "The provided passphrase is invalid",
    "details": "Passphrase must meet security requirements"
  },
  "request_id": "req_987654325",
  "timestamp": "2024-01-15T10:33:00Z"
}

HTTP Status Codes

Status Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
429	Rate Limited	Too many requests
500	Server Error	Internal service error

Rate Limiting

API usage limits and best practices

Default Limits

• 1000 requests per minute
• 10,000 requests per hour
• 100,000 requests per day
• 1,000,000 requests per month

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642248000