API Key Reference

Secure data encryption and decryption services with field-level and deep object encryption support.

Security Best Practices

⚠️ IMPORTANT SECURITY GUIDELINES:

  • Use Environment Variables: Store your API_KEY, PROJECT_ID, and PASSPHRASE in environment variables. Never hardcode credentials.
  • Server-Side Only: Only use this API in server-side applications. Never expose credentials in client-side code.
  • Passphrase Management: Use the same passphrase configured in your dashboard. Store it securely.
  • Credential Security: Treat these credentials like database passwords or private keys.
API Overview
Base URL: https://api.cipherion.cloud/api/v1/crypto
Authentication: API key via x-api-key header
Content-Type: application/json
Authentication
All API requests require authentication using your API key

Required Headers

HeaderTypeRequiredDescription
x-api-keystringYesYour project API key
Content-TypestringYesapplication/json

API Endpoints

Encrypt DataPOST
Encrypts a string of data using your encryption configuration

Endpoint

POST /encrypt/:projectId

URL Parameters

ParameterTypeRequiredDescription
projectIdstringYesYour project identifier from the dashboard

Request Body

{
  "data": "sensitive information to encrypt",
  "passphrase": "your-secure-passphrase"
}

Success Response (200 OK)

{
  "success": true,
  "statusCode": 200,
  "message": "Data encrypted successfully",
  "data": {
    "encrypted_output": "U2FsdGVkX1+jKX9Z3mHq7vK8pQ2..."
  }
}

Error Responses

400 Bad Request - Missing required fields

{
  "success": false,
  "statusCode": 400,
  "message": "Missing required fields: projectId, x-api-key header, data, or passphrase"
}

401 Unauthorized - Invalid API key

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API key"
}

500 Internal Server Error

{
  "success": false,
  "statusCode": 500,
  "message": "Encryption failed",
  "error": "Detailed error message"
}
Common Error Codes
HTTP status codes and their meanings
Status CodeDescription
200Success - Request completed successfully
400Bad Request - Missing required fields or invalid data
401Unauthorized - Invalid or missing API key
403Forbidden - Invalid project ID or insufficient permissions
500Internal Server Error - Server-side processing error
Environment Setup
Required environment variables for your application

Create a .env file:

# API Configuration
PROJECT_ID=your_project_id_here
API_KEY=your_api_key_here
PASSPHRASE=your_encryption_passphrase_here

# Optional: API Base URL (if different from default)
API_BASE_URL={https://api.cipherion.cloud/api/v1/crypto}

Obtaining Credentials

  1. 1.Log in to Dashboard: Access your encryption service dashboard
  2. 2.Create/Select Project: Navigate to your project or create a new one
  3. 3.Generate API Key: Create a new API key for your application
  4. 4.Set Passphrase: Configure your encryption passphrase (this is the same passphrase you'll use in API calls)
  5. 5.Store Securely: Save all credentials in environment variables, never in source code
Best Practices
Essential security and implementation guidelines

1. Credential Management

✅ GOOD - Using environment variables:

const config = {
  projectId: process.env.PROJECT_ID,
  apiKey: process.env.API_KEY,
  passphrase: process.env.PASSPHRASE
};

❌ BAD - Hardcoded credentials:

const config = {
  projectId: 'proj_12345',
  apiKey: 'key_abcdef',
  passphrase: 'my-secret-pass'
};

2. Server-Side Only

✅ GOOD - Backend API route:

// server.js (Node.js/Express)
app.post('/api/secure-data', async (req, res) => {
  const encrypted = await encryptionService.encrypt(req.body.data);
  res.json({ encrypted });
});

❌ BAD - Frontend exposure:

// frontend.js (React/Vue)
const encrypted = await fetch('https://encryption-api.com/encrypt', {
  headers: { 'x-api-key': 'exposed_key' } // NEVER DO THIS
});

3. Passphrase Consistency

Always use the same passphrase for encryption and decryption:

// Store passphrase in environment
const PASSPHRASE = process.env.PASSPHRASE;

// Use consistently
await encrypt(data, PASSPHRASE);
await decrypt(encrypted, PASSPHRASE);
Use Cases
Common scenarios for using encryption endpoints

Simple Encryption

  • API keys and tokens
  • Passwords and secrets
  • Single field values (SSN, credit card numbers)

Deep Encryption

  • User profile objects
  • Payment information structures
  • Complex nested data models
  • Entire database records
Frequently Asked Questions
Common questions about the Encryption API

Q: Can I use different passphrases for different data?

A: While technically possible, it's recommended to use the same passphrase that you configured in the dashboard for consistency. If you need to segment data with different passphrases, consider using separate projects.

Q: What happens if I lose my passphrase?

A: Encrypted data cannot be recovered without the correct passphrase. Always store your passphrase securely and consider having a secure backup mechanism.

Q: Can I use this API from mobile apps?

A: Only if you implement a backend proxy. Never expose API credentials directly in mobile apps. Create a backend service that handles encryption/decryption and communicates with your mobile app.

Q: What's the difference between encrypt and deep_encrypt?

A:

  • encrypt: Encrypts simple string data
  • deep_encrypt: Recursively encrypts complex objects, arrays, and nested structures while preserving the structure

Q: Is there a size limit for encryption?

A: The API accepts payloads up to 15MB. Consider chunking larger data or using compression before encryption.

Q: How long are encrypted outputs?

A: Encrypted output is typically larger than the original data due to encryption overhead, padding, and metadata. Expect approximately 30-50% size increase.

Code Examples

JavaScript / Node.jsPOST
Install dependencies and configure environment variables

Full Application Example

 
// encryption-service.js
require('dotenv').config();
const axios = require('axios');

class EncryptionService {
  constructor() {
    this.baseURL = process.env.API_BASE_URL || 'https://your-api-domain.com/api/v1/crypto';
    this.projectId = process.env.PROJECT_ID;
    this.apiKey = process.env.API_KEY;
    this.passphrase = process.env.PASSPHRASE;
    this.validateConfig();
  }
  
  validateConfig() {
    if (!this.projectId || !this.apiKey || !this.passphrase) {
      throw new Error('Missing required environment variables: PROJECT_ID, API_KEY, PASSPHRASE');
    }
  }
  
  async encrypt(data) {
    try {
      const response = await this.makeRequest('/encrypt', { data });
      return response.data.encrypted_output;
    } catch (error) {
      throw this.handleError('Encryption', error);
    }
  }
  
  async decrypt(encryptedData) {
    try {
      const response = await this.makeRequest('/decrypt', { data: encryptedData });
      return response.data.plaintext;
    } catch (error) {
      throw this.handleError('Decryption', error);
    }
  }
  
  async deepEncrypt(dataObject) {
    try {
      const response = await this.makeRequest('/deep_encrypt', { data: dataObject });
      return { encrypted: response.data.encrypted, meta: response.data.meta };
    } catch (error) {
      throw this.handleError('Deep Encryption', error);
    }
  }
  
  async deepDecrypt(encryptedObject) {
    try {
      const response = await this.makeRequest('/deep_decrypt', { encrypted: encryptedObject });
      return { data: response.data.data, meta: response.data.meta };
    } catch (error) {
      throw this.handleError('Deep Decryption', error);
    }
  }
  
  async makeRequest(endpoint, payload) {
    const response = await axios.post(
      `${this.baseURL}${endpoint}/${this.projectId}`,
      { ...payload, passphrase: this.passphrase },
      {
        headers: {
          'x-api-key': this.apiKey,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.data;
  }
  
  handleError(operation, error) {
    const errorInfo = {
      operation,
      status: error.response?.status,
      message: error.response?.data?.message || error.message,
      details: error.response?.data
    };
    console.error(`${operation} failed:`, errorInfo);
    return new Error(`${operation} failed: ${errorInfo.message} (Status: ${errorInfo.status})`);
  }
}

module.exports = EncryptionService;

// app.js - Usage in Express application
const express = require('express');
const EncryptionService = require('./encryption-service');
const app = express();
app.use(express.json());
const encryptionService = new EncryptionService();

// Endpoint to encrypt user data
app.post('/api/user/create', async (req, res) => {
  try {
    const { username, email, ssn, creditCard } = req.body;
    
    // Deep encrypt sensitive user data
    const sensitiveData = {
      personal: {
        ssn,
        email
      },
      payment: {
        creditCard
      }
    };

const { encrypted, meta } = await encryptionService.deepEncrypt(sensitiveData);
    
    // Store encrypted data in database (pseudocode)
    // await database.users.create({
    //   username,
    //   encryptedData: encrypted,
    //   encryptionMeta: meta
    // });
    
    res.json({
      success: true,
      message: 'User created successfully',
      meta
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      message: error.message
    });
  }
});


// Endpoint to retrieve and decrypt user data
app.get('/api/user/:id', async (req, res) => {
  try {
    // Retrieve encrypted data from database (pseudocode)
    // const user = await database.users.findById(req.params.id);
    
    const encryptedData = {
      /* encrypted data from database */
    };
    
    const { data, meta } = await encryptionService.deepDecrypt(encryptedData);
    
    res.json({
      success: true,
      data,
      meta
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      message: error.message
    });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => { console.log(`Server running on port ${PORT}`); });
Support
Get help with the Encryption API

For technical support, feature requests, or bug reports: