POST /operations

The /operations endpoint provides a generic interface for cryptographic operations with full pipeline processing.

Endpoint

POST /api/v1/operations

Request

Headers

Body

{
  "operation": "encrypt",
  "payload": { ... }
}

Supported Operations

Example Request

curl -X POST https://api.4quays.com/api/v1/operations \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "encrypt",
    "payload": {
      "data": {
        "transferId": "txn-12345",
        "amount": 5000
      },
      "algorithm": "AES-256-GCM",
      "keyId": "key_abc123"
    }
  }'

Response

Success (200 OK)

{
  "requestId": "req_abc123",
  "result": { ... },
  "timestamp": "2026-02-09T10:30:00.000Z"
}

Error Response

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid or expired API key"
  },
  "requestId": "req_abc123"
}

Operation: Encrypt

Encrypt data with a specified algorithm and key.

Request

{
  "operation": "encrypt",
  "payload": {
    "data": { ... },
    "algorithm": "AES-256-GCM",
    "keyId": "key_abc123"
  }
}

Response

{
  "requestId": "req_abc123",
  "result": {
    "ciphertext": "base64-encoded-ciphertext",
    "iv": "base64-encoded-iv",
    "tag": "base64-encoded-tag",
    "algorithm": "AES-256-GCM",
    "keyId": "key_abc123"
  },
  "timestamp": "2026-02-09T10:30:00.000Z"
}

Operation: Decrypt

Decrypt previously encrypted data.

Request

{
  "operation": "decrypt",
  "payload": {
    "ciphertext": "base64-encoded-ciphertext",
    "iv": "base64-encoded-iv",
    "tag": "base64-encoded-tag",
    "algorithm": "AES-256-GCM",
    "keyId": "key_abc123"
  }
}

Response

{
  "requestId": "req_abc123",
  "result": {
    "data": { ... }
  },
  "timestamp": "2026-02-09T10:30:00.000Z"
}

Operation: Sign

Create a digital signature for data.

Request

{
  "operation": "sign",
  "payload": {
    "data": { ... },
    "algorithm": "RSA-SHA256",
    "keyId": "key_signing_123"
  }
}

Response

{
  "requestId": "req_abc123",
  "result": {
    "signature": "base64-encoded-signature",
    "algorithm": "RSA-SHA256",
    "keyId": "key_signing_123"
  },
  "timestamp": "2026-02-09T10:30:00.000Z"
}

Operation: Verify

Verify a digital signature.

Request

{
  "operation": "verify",
  "payload": {
    "data": { ... },
    "signature": "base64-encoded-signature",
    "algorithm": "RSA-SHA256",
    "keyId": "key_signing_123"
  }
}

Response

{
  "requestId": "req_abc123",
  "result": {
    "valid": true
  },
  "timestamp": "2026-02-09T10:30:00.000Z"
}

Operation: Hash

Compute a cryptographic hash.

Request

{
  "operation": "hash",
  "payload": {
    "data": { ... },
    "algorithm": "SHA-256"
  }
}

Response

{
  "requestId": "req_abc123",
  "result": {
    "hash": "base64-encoded-hash",
    "algorithm": "SHA-256"
  },
  "timestamp": "2026-02-09T10:30:00.000Z"
}

Processing Pipeline

Every operation goes through:

1. Request parsing — Validate JSON structure
2. Authentication — Verify API key (bcrypt)
3. Key revocation check — Ensure key is not revoked
4. Policy enforcement — Check operation is allowed
5. Crypto operation — Perform the operation
6. Response transformation — Format the response
7. Audit logging — Log to crypto_operations_audit

Audit Trail

All operations are logged:

When to Use /operations vs /protect

Best Practices

1. Prefer /protect for external integrations — Policies provide abstraction
2. Use /operations for internal crypto — Direct control when needed
3. Always log request IDs — For debugging
4. Handle errors appropriately — Different operations have different failure modes

Related

• POST /protect — Policy-driven protection
• POST /unprotect — Policy-driven unprotection
• Error Codes — Full error reference