Secrets API

Manage secrets with client-side encryption and Zero Knowledge architecture using our official SDKs.

🔐 Overview

The Secrets API allows you to create, retrieve, list, and delete encrypted secrets through our official client libraries. All encryption, authentication, and technical details are handled automatically by the SDKs.

Official SDKs:

• CLI C# Tool - Cross-platform command-line interface
• JavaScript SDK - For Node.js and modern web applications
• JavaScript CDN - Simple browser integration
• Python SDK - Async Python client

📋 List Secrets

Get your company's secrets with automatic pagination.

SDK Usage

CLI C#

sharokey list --status active --limit 10

JavaScript SDK

const secrets = await client.listSecrets({ status: 'active', limit: 10 });

JavaScript CDN

const secrets = await Sharokey.list({ status: 'active', limit: 10 });

Python SDK

secrets = await client.list_secrets(status='active', limit=10)

Response Format

{
  "success": true,
  "message": "Secrets retrieved successfully",
  "data": [
    {
      "slug": "ABC123XY",
      "description": "Database password",
      "message": "Handle with care",
      "creator": "[email protected]",
      "maximum_views": 1,
      "current_views": 0,
      "expiration": "2025-08-11T18:52:37.000000Z",
      "has_password": false,
      "has_attachments": true,
      "attachments_count": 2,
      "is_expired": false,
      "status": "active",
      "created_at": "2025-08-10T18:52:37.000000Z",
      "updated_at": "2025-08-10T18:52:37.000000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 125,
    "last_page": 3
  }
}

✨ Create Secret

Create a new encrypted secret with optional attachments.

SDK Usage

CLI C#

sharokey create "My secret content" --hours 24 --views 1 --description "Database credentials"

JavaScript SDK

const secret = await client.createSecret("My secret content", {
  hours: 24,
  views: 1,
  description: "Database credentials",
  password: "secure123"
});

JavaScript CDN

const secret = await Sharokey.create("My secret content", 24, 1, {
  description: "Database credentials",
  password: "secure123"
});

Python SDK

secret = await client.create("My secret content", 
  hours=24, 
  views=1,
  description="Database credentials",
  password="secure123"
)

Response Format

{
  "success": true,
  "message": "Secret created successfully",
  "data": {
    "slug": "ABC123XY",
    "description": "Database credentials",
    "message": "Use within 24 hours", 
    "expires_in_hours": 24,
    "maximum_views": 1,
    "current_views": 0,
    "expiration": "2025-08-11T18:52:37.000000Z",
    "has_attachments": true,
    "attachments_count": 1,
    "share_url": "https://passlink.domaindev/ABC123XY#keyB_part_here",
    "created_at": "2025-08-10T18:52:37.000000Z"
  }
}

👁️ Get Secret Details

Retrieve metadata for a specific secret (without decrypting content).

SDK Usage

CLI C#

sharokey get ABC123XY --details-only

JavaScript SDK

const details = await client.getSecretDetails("ABC123XY");

JavaScript CDN

const details = await Sharokey.getDetails("ABC123XY");

Python SDK

details = await client.get_details("ABC123XY")

Response Format

{
  "success": true,
  "data": {
    "slug": "ABC123XY",
    "description": "Database credentials",
    "message": "Use within 24 hours",
    "creator": "[email protected]",
    "maximum_views": 1,
    "current_views": 0,
    "expiration": "2025-08-11T18:52:37.000000Z",
    "has_password": true,
    "has_attachments": true,
    "attachments": [
      {
        "name": "config.json"
      }
    ],
    "captcha": false,
    "otp_type": "email",
    "ip_whitelist": "192.168.1.0/24,10.0.0.1",
    "geolocation": "FR,US,CA",
    "is_expired": false,
    "status": "active",
    "share_url": "https://passlink.domaindev/ABC123XY",
    "created_at": "2025-08-10T18:52:37.000000Z",
    "updated_at": "2025-08-10T18:52:37.000000Z"
  }
}

🗑️ Delete Secret

Delete a secret by clearing its content and expiring it immediately.

SDK Usage

CLI C#

sharokey delete ABC123XY

JavaScript SDK

await client.deleteSecret("ABC123XY");

JavaScript CDN

await Sharokey.delete("ABC123XY");

Python SDK

await client.delete("ABC123XY")

Response Format

{
  "success": true,
  "message": "Secret deleted successfully",
  "data": null
}

📊 Company Statistics

Get usage statistics for your company.

SDK Usage

CLI C#

sharokey stats

JavaScript SDK

const stats = await client.getStats();

JavaScript CDN

const stats = await Sharokey.getStats();

Python SDK

stats = await client.get_stats()

Response Format

{
  "success": true,
  "message": "Secrets statistics retrieved successfully",
  "data": {
    "total_secrets": 1247,
    "active_secrets": 89,
    "expired_secrets": 1158,
    "total_views": 5432,
    "secrets_with_password": 156,
    "secrets_created_today": 12,
    "secrets_created_this_week": 87,
    "secrets_created_this_month": 234
  }
}

🚨 Error Responses

All SDKs handle these errors automatically and provide structured error objects.

Authentication Errors

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Token is invalid or expired"
  }
}

Validation Errors

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The content field is required",
    "details": {
      "content": ["The content field is required"],
      "expiration": ["Must be between 1 and 1000 hours"]
    }
  }
}

Quota Exceeded

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED", 
    "message": "You have reached the maximum allowed secrets for your current plan."
  }
}

Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Secret not found or expired"
  }
}

Permission Denied

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions to create secrets"
  }
}

🔐 Security & Encryption

Zero Knowledge Architecture

All SDKs implement client-side encryption automatically:

• Algorithm: AES-256-GCM with PBKDF2 key derivation
• Key split: Server stores keyA, URL fragment contains keyB
• IV/Salt: Generated automatically per secret
• No plaintext: Server never sees your secret content

SDK Security Features

• Automatic token management and secure storage
• Client-side encryption before transmission
• Secure key generation and splitting
• Input validation and sanitization
• Error handling without data exposure

🔗 Related Documentation

• CLI C# Documentation - Command-line interface guide
• JavaScript SDK - Browser and Node.js integration
• Python SDK - Async Python client
• File Attachments - Attachment handling
• Authentication - API token management