API Documentation

English

Français

English

Français

Appearance

Company Statistics API ​

Get comprehensive usage statistics for your company using our official SDKs.

📊 Overview ​

Get detailed insights into your company's secret usage, creation patterns, and security metrics. All statistics are automatically scoped to your company and handled seamlessly by our SDKs.

Official SDKs:

📈 Get Company Statistics ​

Retrieve comprehensive statistics for your company's secret usage.

SDK Usage ​

bash
sharokey stats
javascript
const stats = await client.getStats();
javascript
const stats = await Sharokey.getStats();
python
stats = await client.get_stats()

Response Format ​

json
{
  "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
  },
  "meta": {
    "version": "v1",
    "timestamp": "2025-08-11T08:33:42.208967Z"
  }
}

Statistics Fields ​

FieldTypeDescription
total_secretsintegerTotal number of secrets created by your company
active_secretsintegerSecrets that are not expired and haven't reached view limit
expired_secretsintegerSecrets that have expired or reached maximum views
total_viewsintegerTotal number of times secrets have been viewed
secrets_with_passwordintegerNumber of secrets protected with additional passwords
secrets_created_todayintegerSecrets created in the last 24 hours
secrets_created_this_weekintegerSecrets created in the last 7 days
secrets_created_this_monthintegerSecrets created in the last 30 days

Status Calculation ​

Active Secret Definition:

  • Expiration date is in the future (or null)
  • Current views < maximum views
  • Not manually deleted

Expired Secret Definition:

  • Expiration date has passed, OR
  • Current views >= maximum views, OR
  • Manually deleted (content cleared)

🔍 Statistics Insights ​

Usage Patterns ​

High Activity Indicators:

  • secrets_created_today > 10
  • secrets_created_this_week > 50
  • High ratio of secrets_with_password (security-conscious usage)

Security Metrics:

  • Password Protection Rate: secrets_with_password / total_secrets * 100
  • View Efficiency: total_views / total_secrets (average views per secret)
  • Expiration Rate: expired_secrets / total_secrets * 100

Retention Analysis ​

Active vs. Total Ratio:

Active Rate = (active_secrets / total_secrets) * 100
  • High Active Rate (>20%): Recent usage, longer expiration times
  • Low Active Rate (<5%): Short-lived secrets, high security posture

📊 Usage Recommendations ​

Security Best Practices ​

If secrets_with_password < 30% of total_secrets:

  • Consider implementing password protection for sensitive content
  • Review security policies with team members

If active_secrets > 50% of total_secrets:

  • Review expiration policies - secrets may be living too long
  • Consider shorter default expiration times

Performance Optimization ​

High Volume Usage (secrets_created_today > 50):

  • Monitor API rate limits carefully
  • Consider implementing client-side request queuing
  • Use bulk operations where available

🚨 Error Responses ​

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

Authentication Error ​

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

Permission Error ​

json
{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions to read company stats"
  }
}

Rate Limit Exceeded ​

json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

🔐 Security & Privacy ​

Company Isolation ​

  • Statistics automatically filtered to your company
  • No cross-company data leakage possible
  • Token scope enforced automatically by SDKs

Data Privacy ​

  • Statistics do not include secret content or metadata
  • Only aggregated counts and dates are returned
  • Individual secret details not exposed

💡 Integration Examples ​

Dashboard Widget ​

bash
# Get stats and format for display
sharokey stats --format json | jq '.data.total_secrets'
javascript
// Fetch and display company stats
const stats = await client.getStats();
document.getElementById('total-secrets').textContent = stats.total_secrets;
document.getElementById('active-secrets').textContent = stats.active_secrets;
javascript
// Simple dashboard update
const stats = await Sharokey.getStats();
console.log(`Active secrets: ${stats.active_secrets}`);
python
# Calculate security metrics
stats = await client.get_stats()
password_rate = (stats.secrets_with_password / stats.total_secrets) * 100
print(f"Password protection rate: {password_rate:.1f}%")

CLI Monitoring ​

bash
# Check daily secret creation
DAILY_COUNT=$(sharokey stats --field secrets_created_today)
if [ "$DAILY_COUNT" -gt 100 ]; then
  echo "High usage detected: $DAILY_COUNT secrets created today"
fi

Automated Reporting ​

javascript
// Weekly usage report
const stats = await client.getStats();
const report = {
  weekly_creation: stats.secrets_created_this_week,
  security_score: (stats.secrets_with_password / stats.total_secrets) * 100,
  active_ratio: (stats.active_secrets / stats.total_secrets) * 100
};
console.log('Weekly Report:', report);
python
# Security analysis
stats = await client.get_stats()
analysis = {
    'password_protection_rate': (stats.secrets_with_password / stats.total_secrets) * 100,
    'activity_level': 'high' if stats.secrets_created_today > 10 else 'normal',
    'retention_health': 'good' if stats.active_secrets / stats.total_secrets < 0.2 else 'review'
}
print(f"Security Analysis: {analysis}")

All statistics are calculated in real-time and reflect the current state of your company's secret usage.

Released under the MIT License.

Copyright © 2025 Sharokey