Secret Requests API

Create, manage, and track secret requests to solicit secure information from third parties using our official SDKs.

🔐 Overview

The Secret Requests API allows you to create requests that ask others to share secrets with you securely. Recipients can respond to your requests through a secure web interface, and the shared secrets will be encrypted using Zero Knowledge architecture.

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 Secret Requests

Get your company's secret requests with automatic pagination.

SDK Usage

CLI C#JavaScript SDKJavaScript CDNPython SDK

bash

sharokey list-requests --status active --limit 10

javascript

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

javascript

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

python

requests = await client.list_requests(status='active', limit=10)

Response Format

json

{
  "success": true,
  "message": "Secret requests retrieved successfully",
  "data": [
    {
      "id": 123,
      "token": "req_ABC123XY",
      "message": "Please share the database credentials",
      "description": "Production DB access needed",
      "secret_expiration_hours": 24,
      "request_expiration_hours": 48,
      "maximum_views": 1,
      "email_to": "[email protected]",
      "email_reply": "[email protected]",
      "creator": "[email protected]",
      "secret_expiration": "2025-08-12T18:52:37.000000Z",
      "request_expiration": "2025-08-11T18:52:37.000000Z",
      "status": "active",
      "url": "https://passlink.domaindev/request/req_ABC123XY",
      "created_at": "2025-08-10T18:52:37.000000Z",
      "updated_at": "2025-08-10T18:52:37.000000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 25,
    "last_page": 1
  }
}

✨ Create Secret Request

Create a new secret request to solicit secure information from others.

SDK Usage

CLI C#JavaScript SDKJavaScript CDNPython SDK

bash

sharokey create-request --message "Please share the credentials" --description "DB access" --secret-hours 24 --request-hours 48 --max-views 1 --email-to "[email protected]"

javascript

const request = await client.createSecretRequest({
  message: "Please share the database credentials",
  description: "Production DB access needed",
  secretExpirationHours: 24,
  requestExpirationHours: 48,
  maximumViews: 1,
  emailTo: "[email protected]",
  emailReply: "[email protected]"
});

javascript

const request = await Sharokey.createRequest({
  message: "Please share the database credentials",
  description: "Production DB access needed",
  secretExpirationHours: 24,
  requestExpirationHours: 48,
  maximumViews: 1,
  emailTo: "[email protected]"
});

python

request = await client.create_request(
  message="Please share the database credentials",
  description="Production DB access needed",
  secret_expiration_hours=24,
  request_expiration_hours=48,
  maximum_views=1,
  email_to="[email protected]",
  email_reply="[email protected]"
)

Response Format

json

{
  "success": true,
  "message": "Secret request created successfully",
  "data": {
    "id": 123,
    "token": "req_ABC123XY",
    "message": "Please share the database credentials",
    "description": "Production DB access needed",
    "secret_expiration_hours": 24,
    "request_expiration_hours": 48,
    "maximum_views": 1,
    "email_to": "[email protected]",
    "email_reply": "[email protected]",
    "creator": "[email protected]",
    "secret_expiration": "2025-08-12T18:52:37.000000Z",
    "request_expiration": "2025-08-11T18:52:37.000000Z",
    "status": "active",
    "url": "https://passlink.domaindev/request/req_ABC123XY",
    "created_at": "2025-08-10T18:52:37.000000Z"
  }
}

👁️ Get Secret Request Details

Retrieve details for a specific secret request.

SDK Usage

CLI C#JavaScript SDKJavaScript CDNPython SDK

bash

sharokey get-request 123

javascript

const request = await client.getSecretRequest(123);

javascript

const request = await Sharokey.getRequest(123);

python

request = await client.get_request(123)

Response Format

json

{
  "success": true,
  "data": {
    "id": 123,
    "token": "req_ABC123XY",
    "message": "Please share the database credentials",
    "description": "Production DB access needed",
    "secret_expiration_hours": 24,
    "request_expiration_hours": 48,
    "maximum_views": 1,
    "email_to": "[email protected]",
    "email_reply": "[email protected]",
    "creator": "[email protected]",
    "secret_expiration": "2025-08-12T18:52:37.000000Z",
    "request_expiration": "2025-08-11T18:52:37.000000Z",
    "status": "active",
    "url": "https://passlink.domaindev/request/req_ABC123XY",
    "created_at": "2025-08-10T18:52:37.000000Z",
    "updated_at": "2025-08-10T18:52:37.000000Z"
  }
}

🗑️ Delete Secret Request

Delete a secret request and invalidate its public URL.

SDK Usage

CLI C#JavaScript SDKJavaScript CDNPython SDK

bash

sharokey delete-request 123

javascript

await client.deleteSecretRequest(123);

javascript

await Sharokey.deleteRequest(123);

python

await client.delete_request(123)

Response Format

json

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

📊 Secret Request Statistics

Get usage statistics for your company's secret requests.

SDK Usage

CLI C#JavaScript SDKJavaScript CDNPython SDK

bash

sharokey request-stats

javascript

const stats = await client.getSecretRequestStatistics();

javascript

const stats = await Sharokey.requestStats();

python

stats = await client.request_stats()

Response Format

json

{
  "success": true,
  "message": "Secret request statistics retrieved successfully",
  "data": {
    "total_requests": 156,
    "active_requests": 23,
    "expired_requests": 133,
    "requests_created_today": 5,
    "requests_created_this_week": 18,
    "requests_created_this_month": 42,
    "average_response_time_hours": 6.4
  }
}

🚨 Error Responses

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

Authentication Errors

json

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

Validation Errors

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The secret_expiration_hours field must be between 1 and 1000",
    "details": {
      "secret_expiration_hours": ["Must be between 1 and 1000"],
      "maximum_views": ["Must be between 1 and 10"],
      "email_to": ["Must be a valid email address"]
    }
  }
}

Quota Exceeded

json

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

Not Found

json

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

Permission Denied

json

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

📝 Request Parameters

Secret Request Creation

Parameter	Type	Required	Description	Validation
`message`	string	No	Message displayed to the recipient	Max 255 characters
`description`	string	No	Internal description for your reference	Max 255 characters
`secret_expiration_hours`	integer	No	Hours until shared secret expires	1-1000, default: 24
`request_expiration_hours`	integer	No	Hours until request expires	1-1000, default: 48
`maximum_views`	integer	No	Maximum views for shared secret	1-10, default: 1
`email_to`	string	No	Email address to send request to	Valid email format
`email_reply`	string	No	Reply-to email for notifications	Valid email format

Filtering Parameters

Parameter	Type	Description
`status`	string	Filter by status: `active`, `expired`
`creator`	string	Filter by creator email address
`search`	string	Search in message and description fields
`limit`	integer	Number of results per page (default: 50, max: 100)
`page`	integer	Page number for pagination

🔐 Security & Workflow

How Secret Requests Work

Create Request: You create a secret request with your requirements
Share URL: Send the generated URL to your contact (email optional)
Recipient Response: They visit the URL and share their secret securely
Zero Knowledge: Their secret is encrypted client-side before submission
Notification: You receive a notification when the secret is shared
Secure Access: Access the shared secret through your dashboard

Security Features

Zero Knowledge Architecture: Recipients' secrets are encrypted client-side
Time-based Expiration: Both request and resulting secrets can expire
View Limits: Control how many times the shared secret can be accessed
Email Notifications: Optional automated emails for request delivery
Audit Trail: Complete logging of request creation and responses

CLI C# Documentation - Command-line interface guide
JavaScript SDK - Browser and Node.js integration
Python SDK - Async Python client
Secrets API - Standard secret management
Authentication - API token management

Secret Requests API ​

🔐 Overview ​

📋 List Secret Requests ​

SDK Usage ​

Response Format ​

✨ Create Secret Request ​

SDK Usage ​

Response Format ​

👁️ Get Secret Request Details ​

SDK Usage ​

Response Format ​

🗑️ Delete Secret Request ​

SDK Usage ​

Response Format ​

📊 Secret Request Statistics ​

SDK Usage ​

Response Format ​

🚨 Error Responses ​

Authentication Errors ​

Validation Errors ​

Quota Exceeded ​

Not Found ​

Permission Denied ​

📝 Request Parameters ​

Secret Request Creation ​

Filtering Parameters ​

🔐 Security & Workflow ​

How Secret Requests Work ​

Security Features ​

🔗 Related Documentation ​

Secret Requests API

🔐 Overview

📋 List Secret Requests

SDK Usage

Response Format

✨ Create Secret Request

SDK Usage

Response Format

👁️ Get Secret Request Details

SDK Usage

Response Format

🗑️ Delete Secret Request

SDK Usage

Response Format

📊 Secret Request Statistics

SDK Usage

Response Format

🚨 Error Responses

Authentication Errors

Validation Errors

Quota Exceeded

Not Found

Permission Denied

📝 Request Parameters

Secret Request Creation

Filtering Parameters

🔐 Security & Workflow

How Secret Requests Work

Security Features

🔗 Related Documentation