API Reference

Complete API documentation for programmatic access to ShieldCipher services.

Base URL

All API requests should be made to:

https://www.shieldcipher.com/api

Authentication

API requests require authentication using API keys:

Authorization: Bearer YOUR_API_KEY

Or include API key and secret in request headers:

X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET

License Endpoints

Validate License

Endpoint: POST /license/validate

Description: Validate a license key and get license information.

Request Body:

{
  "key": "your-license-key-here"
}

Response:

{
  "valid": true,
  "status": "active",
  "product": "my-product",
  "plan": "subscription",
  "seats": 5,
  "seats_used": 2,
  "expires_at": "2025-12-31T23:59:59Z",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Activate License

Endpoint: POST /license/activate

Description: Activate a license on a specific device.

Request Body:

{
  "key": "your-license-key",
  "product": "my-product",
  "device_hash": "ABC123...",
  "device_label": "Production Server",
  "domain": "example.com"
}

Response:

{
  "success": true,
  "lat": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "seats_used": 1,
  "seats_available": 4
}

Refresh License Token

Endpoint: POST /license/refresh

Description: Refresh an expiring LAT token.

Request Body:

{
  "key": "your-license-key",
  "device_hash": "ABC123..."
}

Deactivate License

Endpoint: POST /license/deactivate

Description: Deactivate a license on a device (frees up a seat).

Request Body:

{
  "key": "your-license-key",
  "device_hash": "ABC123..."
}

Get License Status

Endpoint: GET /license/status

Query Parameters:

• key - License key
• device_hash - Device hash (optional)

Package Management Endpoints

Upload Package

Endpoint: POST /admin/packages/upload

Description: Upload a ZIP file for protection.

Request: Multipart form data

• product_id - Product ID
• name - Package name
• version_id - Version ID (optional)
• zip_file - ZIP file upload

Lock Package

Endpoint: POST /admin/packages/{id}/lock

Description: Encrypt package in secure vault.

Request Body:

{
  "passphrase": "optional-passphrase"
}

Encode Package

Endpoint: POST /admin/packages/{id}/encode

Description: Queue package for encoding.

Request Body:

{
  "profile_id": 2,
  "options": {}
}

Get Package Status

Endpoint: GET /admin/packages/{id}/status

Description: Get encoding status and logs.

Download Endpoints

Get Download Access

Endpoint: GET /downloads/access

Query Parameters:

• license_id - License ID
• device_hash - Device hash

Response:

{
  "downloads": [
    {
      "version": "1.0.0",
      "url": "https://...",
      "sha256": "...",
      "expires_at": "2025-01-13T10:00:00Z"
    }
  ]
}

Get Download

Endpoint: GET /downloads/get

Description: Download protected package with signed URL.

Query Parameters:

• url - Signed download URL
• signature - URL signature

Check for Updates

Endpoint: GET /updates/check

Query Parameters:

• license_id - License ID
• device_hash - Device hash
• current - Current version
• channel - Update channel (stable, beta, alpha)

Webhook Events

ShieldCipher sends webhook events for various actions:

Event Types

• license.activated - License activated on device
• license.deactivated - License deactivated
• license.expired - License expired
• security.alert - Security event detected
• package.encoded - Package encoding completed

Webhook Payload Format

{
  "event": "license.activated",
  "timestamp": "2025-01-12T10:30:00Z",
  "data": {
    // Event-specific data
  },
  "signature": {
    "algorithm": "ed25519",
    "kid": "psk:prod:v3",
    "signature": "base64_signature"
  }
}

Error Codes

API errors follow standard HTTP status codes:

• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (resource doesn't exist)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Error Response Format

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    // Additional error details
  }
}

Rate Limits

API rate limits are enforced per API key:

• Standard Plans: 100 requests per minute
• Professional Plans: 500 requests per minute
• Enterprise Plans: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642000000

Request Signing

For enhanced security, requests can be signed:

Required Headers

• X-Sign-Alg - Algorithm (ed25519)
• X-Sign-KID - Key ID
• X-Sign-TS - Timestamp (ISO 8601)
• X-Sign-Nonce - Unique nonce
• X-Sign-BodySHA256 - Body hash
• X-Sign-Signature - Request signature

SDK Examples

Use our SDKs for easier API integration. See Integration Guides for examples.