Skip to main content
GET
/
v1
/
developer
/
keys
List API Keys
curl --request GET \
  --url https://api-mainnet.onzks.com/v1/developer/keys \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "keys": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "permissions": [
        {
          "resource": "<string>",
          "actions": [
            {}
          ],
          "restrictions": {}
        }
      ],
      "rateLimit": {
        "requestsPerMinute": 123,
        "requestsPerHour": 123,
        "requestsPerDay": 123,
        "burstLimit": 123
      },
      "status": "<string>",
      "createdAt": "<string>",
      "expiry": "<string>",
      "lastUsed": "<string>",
      "usage": {
        "totalRequests": 123,
        "requestsToday": 123,
        "requestsThisWeek": 123,
        "requestsThisMonth": 123,
        "averageRequestsPerDay": 123,
        "peakRequestsPerHour": 123,
        "lastRequestAt": "<string>"
      },
      "webhooks": [
        {
          "id": "<string>",
          "url": "<string>",
          "events": [
            {}
          ],
          "status": "<string>",
          "lastDelivery": "<string>",
          "deliveryCount": 123,
          "failureCount": 123
        }
      ],
      "metadata": {}
    }
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "hasMore": true
  },
  "summary": {
    "totalKeys": 123,
    "activeKeys": 123,
    "inactiveKeys": 123,
    "expiredKeys": 123,
    "revokedKeys": 123,
    "totalRequests": 123,
    "requestsToday": 123,
    "averageRequestsPerKey": 123
  },
  "timestamp": "<string>"
}

​
Overview

Retrieve all API keys associated with your account. This endpoint provides comprehensive information about your API keys including their status, permissions, usage statistics, and configuration details.
Use this endpoint to monitor your API keys, check their status, and manage your API key inventory. The actual API key values are masked for security.

​
Parameters

​
status
string
Filter by API key status
  • active - Active API keys (default)
  • inactive - Inactive API keys
  • expired - Expired API keys
  • revoked - Revoked API keys
  • all - All API keys regardless of status
​
permission
string
Filter by permission resource
  • identity - Identity management keys
  • scores - Score query keys
  • achievements - Achievement keys
  • trading - Trading data keys
  • trust - Trust layer keys
  • attestations - Attestation keys
  • all - All permissions
​
search
string
Search by API key name or description
​
sortBy
string
Sort API keys by field
  • createdAt - By creation date (default)
  • lastUsed - By last use date
  • name - By name
  • usage - By usage count
​
sortOrder
string
Sort order
  • desc - Descending (default)
  • asc - Ascending
​
limit
number
Number of API keys to return (default: 50, max: 100)
​
offset
number
Number of API keys to skip for pagination (default: 0)
​
includeUsage
boolean
Include usage statistics (default: true)
​
includeWebhooks
boolean
Include webhook configurations (default: true)

​
Response

​
success
boolean
Indicates if the request was successful
​
keys
array
Array of API key objects
​
pagination
object
Pagination information
​
summary
object
API key summary statistics
​
timestamp
string
ISO 8601 timestamp of the response

​
Examples

curl "https://api.onzks.com/v1/developer/keys" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Example

{
  "success": true,
  "keys": [
    {
      "id": "key_1234567890abcdef",
      "name": "Production App",
      "description": "API key for production application",
      "permissions": [
        {
          "resource": "scores",
          "actions": ["read"],
          "restrictions": {}
        },
        {
          "resource": "identity",
          "actions": ["read"],
          "restrictions": {}
        }
      ],
      "rateLimit": {
        "requestsPerMinute": 100,
        "requestsPerHour": 1000,
        "requestsPerDay": 10000,
        "burstLimit": 150
      },
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "expiry": null,
      "lastUsed": "2024-01-20T14:30:00Z",
      "usage": {
        "totalRequests": 15420,
        "requestsToday": 1250,
        "requestsThisWeek": 8750,
        "requestsThisMonth": 15420,
        "averageRequestsPerDay": 1028,
        "peakRequestsPerHour": 150,
        "lastRequestAt": "2024-01-20T14:30:00Z"
      },
      "webhooks": [
        {
          "id": "webhook_1234567890abcdef",
          "url": "https://myapp.com/webhooks/zkscore",
          "events": ["score.updated", "achievement.earned"],
          "status": "active",
          "lastDelivery": "2024-01-20T14:25:00Z",
          "deliveryCount": 1250,
          "failureCount": 5
        }
      ],
      "metadata": {
        "environment": "production",
        "version": "1.0.0"
      }
    },
    {
      "id": "key_abcdef1234567890",
      "name": "Development Testing",
      "description": "API key for development testing",
      "permissions": [
        {
          "resource": "all",
          "actions": ["all"],
          "restrictions": {}
        }
      ],
      "rateLimit": {
        "requestsPerMinute": 50,
        "requestsPerHour": 500,
        "requestsPerDay": 5000,
        "burstLimit": 75
      },
      "status": "active",
      "createdAt": "2024-01-10T09:15:00Z",
      "expiry": "2024-04-10T09:15:00Z",
      "lastUsed": "2024-01-19T16:45:00Z",
      "usage": {
        "totalRequests": 3250,
        "requestsToday": 150,
        "requestsThisWeek": 1050,
        "requestsThisMonth": 3250,
        "averageRequestsPerDay": 325,
        "peakRequestsPerHour": 25,
        "lastRequestAt": "2024-01-19T16:45:00Z"
      },
      "webhooks": [],
      "metadata": {
        "environment": "development",
        "version": "0.9.0"
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "summary": {
    "totalKeys": 5,
    "activeKeys": 4,
    "inactiveKeys": 0,
    "expiredKeys": 0,
    "revokedKeys": 1,
    "totalRequests": 18670,
    "requestsToday": 1400,
    "averageRequestsPerKey": 3734
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

​
Use Cases

​
1. API Key Management Dashboard

Create a comprehensive management dashboard: 
function createApiKeyDashboard(keys) {
  const dashboard = {
    overview: {
      total: keys.length,
      active: keys.filter(k => k.status === 'active').length,
      expired: keys.filter(k => k.status === 'expired').length,
      revoked: keys.filter(k => k.status === 'revoked').length
    },
    usage: {
      totalRequests: keys.reduce((sum, k) => sum + k.usage.totalRequests, 0),
      requestsToday: keys.reduce((sum, k) => sum + k.usage.requestsToday, 0),
      averagePerKey: keys.reduce((sum, k) => sum + k.usage.averageRequestsPerDay, 0) / keys.length
    },
    alerts: generateAlerts(keys),
    recommendations: generateRecommendations(keys)
  };
  
  return dashboard;
}

function generateAlerts(keys) {
  const alerts = [];
  
  keys.forEach(key => {
    if (key.status === 'expired') {
      alerts.push({
        type: 'expired',
        message: `API key "${key.name}" has expired`,
        keyId: key.id
      });
    }
    
    if (key.usage.requestsToday > key.rateLimit.requestsPerDay * 0.9) {
      alerts.push({
        type: 'rate_limit',
        message: `API key "${key.name}" is approaching daily limit`,
        keyId: key.id
      });
    }
    
    if (key.lastUsed && Date.now() - new Date(key.lastUsed) > 30 * 24 * 60 * 60 * 1000) {
      alerts.push({
        type: 'unused',
        message: `API key "${key.name}" has not been used in 30 days`,
        keyId: key.id
      });
    }
  });
  
  return alerts;
}

​
2. Usage Analytics

Analyze API key usage patterns: 
function analyzeUsage(keys) {
  const analysis = {
    byKey: keys.map(key => ({
      id: key.id,
      name: key.name,
      usage: key.usage,
      efficiency: key.usage.totalRequests / key.rateLimit.requestsPerDay,
      trend: calculateTrend(key.usage)
    })),
    overall: {
      totalRequests: keys.reduce((sum, k) => sum + k.usage.totalRequests, 0),
      averageEfficiency: keys.reduce((sum, k) => sum + (k.usage.totalRequests / k.rateLimit.requestsPerDay), 0) / keys.length,
      peakUsage: Math.max(...keys.map(k => k.usage.peakRequestsPerHour))
    },
    recommendations: generateUsageRecommendations(keys)
  };
  
  return analysis;
}

function calculateTrend(usage) {
  const today = usage.requestsToday;
  const thisWeek = usage.requestsThisWeek;
  const thisMonth = usage.requestsThisMonth;
  
  const weeklyAverage = thisWeek / 7;
  const monthlyAverage = thisMonth / 30;
  
  if (today > weeklyAverage * 1.2) return 'increasing';
  if (today < weeklyAverage * 0.8) return 'decreasing';
  return 'stable';
}

​
3. Permission Analysis

Analyze API key permissions: 
function analyzePermissions(keys) {
  const permissionStats = {};
  
  keys.forEach(key => {
    key.permissions.forEach(permission => {
      if (!permissionStats[permission.resource]) {
        permissionStats[permission.resource] = {
          count: 0,
          actions: new Set(),
          keys: []
        };
      }
      
      permissionStats[permission.resource].count++;
      permission.actions.forEach(action => {
        permissionStats[permission.resource].actions.add(action);
      });
      permissionStats[permission.resource].keys.push(key.id);
    });
  });
  
  return {
    byResource: Object.entries(permissionStats).map(([resource, stats]) => ({
      resource,
      count: stats.count,
      actions: Array.from(stats.actions),
      keys: stats.keys
    })),
    recommendations: generatePermissionRecommendations(permissionStats)
  };
}

​
4. Webhook Monitoring

Monitor webhook configurations: 
function monitorWebhooks(keys) {
  const webhookStats = {
    total: 0,
    active: 0,
    failed: 0,
    byStatus: {},
    byEvent: {},
    recommendations: []
  };
  
  keys.forEach(key => {
    key.webhooks.forEach(webhook => {
      webhookStats.total++;
      webhookStats.byStatus[webhook.status] = (webhookStats.byStatus[webhook.status] || 0) + 1;
      
      if (webhook.status === 'active') webhookStats.active++;
      if (webhook.status === 'failed') webhookStats.failed++;
      
      webhook.events.forEach(event => {
        webhookStats.byEvent[event] = (webhookStats.byEvent[event] || 0) + 1;
      });
      
      // Check for webhook issues
      if (webhook.failureCount > webhook.deliveryCount * 0.1) {
        webhookStats.recommendations.push({
          type: 'high_failure_rate',
          message: `Webhook for ${key.name} has high failure rate`,
          webhookId: webhook.id,
          failureRate: webhook.failureCount / webhook.deliveryCount
        });
      }
    });
  });
  
  return webhookStats;
}

​
5. Key Rotation Planning

Plan API key rotations: 
function planKeyRotations(keys) {
  const rotations = [];
  
  keys.forEach(key => {
    const daysUntilExpiry = key.expiry ? 
      Math.ceil((new Date(key.expiry) - new Date()) / (1000 * 60 * 60 * 24)) : null;
    
    if (daysUntilExpiry && daysUntilExpiry < 30) {
      rotations.push({
        keyId: key.id,
        name: key.name,
        type: 'expiry',
        urgency: daysUntilExpiry < 7 ? 'high' : 'medium',
        daysUntilExpiry,
        recommendation: 'Rotate key before expiry'
      });
    }
    
    if (key.usage.totalRequests > key.rateLimit.requestsPerDay * 0.8) {
      rotations.push({
        keyId: key.id,
        name: key.name,
        type: 'usage',
        urgency: 'medium',
        usage: key.usage.totalRequests,
        recommendation: 'Consider upgrading rate limits or rotating key'
      });
    }
    
    if (key.lastUsed && Date.now() - new Date(key.lastUsed) > 90 * 24 * 60 * 60 * 1000) {
      rotations.push({
        keyId: key.id,
        name: key.name,
        type: 'unused',
        urgency: 'low',
        daysSinceLastUse: Math.ceil((Date.now() - new Date(key.lastUsed)) / (1000 * 60 * 60 * 24)),
        recommendation: 'Consider revoking unused key'
      });
    }
  });
  
  return rotations.sort((a, b) => {
    const urgencyOrder = { high: 3, medium: 2, low: 1 };
    return urgencyOrder[b.urgency] - urgencyOrder[a.urgency];
  });
}

​
Best Practices

​
1. Regular Monitoring

Monitor API keys regularly: 
async function monitorApiKeys() {
  const keys = await listApiKeys({ status: 'all' });
  
  const monitoring = {
    expired: keys.keys.filter(k => k.status === 'expired'),
    expiring: keys.keys.filter(k => k.expiry && new Date(k.expiry) < new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)),
    unused: keys.keys.filter(k => k.lastUsed && Date.now() - new Date(k.lastUsed) > 30 * 24 * 60 * 60 * 1000),
    highUsage: keys.keys.filter(k => k.usage.requestsToday > k.rateLimit.requestsPerDay * 0.8)
  };
  
  return monitoring;
}

​
2. Automated Alerts

Set up automated alerts: 
function setupAlerts(keys) {
  const alerts = [];
  
  keys.forEach(key => {
    // Expiry alerts
    if (key.expiry) {
      const daysUntilExpiry = Math.ceil((new Date(key.expiry) - new Date()) / (1000 * 60 * 60 * 24));
      if (daysUntilExpiry <= 7) {
        alerts.push({
          type: 'expiry_warning',
          keyId: key.id,
          message: `API key "${key.name}" expires in ${daysUntilExpiry} days`
        });
      }
    }
    
    // Usage alerts
    if (key.usage.requestsToday > key.rateLimit.requestsPerDay * 0.9) {
      alerts.push({
        type: 'usage_warning',
        keyId: key.id,
        message: `API key "${key.name}" is at 90% of daily limit`
      });
    }
    
    // Unused key alerts
    if (key.lastUsed && Date.now() - new Date(key.lastUsed) > 60 * 24 * 60 * 60 * 1000) {
      alerts.push({
        type: 'unused_warning',
        keyId: key.id,
        message: `API key "${key.name}" has not been used in 60 days`
      });
    }
  });
  
  return alerts;
}

​
3. Key Lifecycle Management

Manage key lifecycle: 
async function manageKeyLifecycle() {
  const keys = await listApiKeys({ status: 'all' });
  
  const lifecycle = {
    active: keys.keys.filter(k => k.status === 'active'),
    expired: keys.keys.filter(k => k.status === 'expired'),
    revoked: keys.keys.filter(k => k.status === 'revoked'),
    needsRotation: keys.keys.filter(k => {
      if (k.expiry && new Date(k.expiry) < new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)) {
        return true;
      }
      if (k.usage.totalRequests > k.rateLimit.requestsPerDay * 0.8) {
        return true;
      }
      return false;
    })
  };
  
  return lifecycle;
}

​
4. Usage Optimization

Optimize API key usage: 
function optimizeUsage(keys) {
  const optimization = {
    underutilized: keys.filter(k => k.usage.totalRequests < k.rateLimit.requestsPerDay * 0.1),
    overutilized: keys.filter(k => k.usage.totalRequests > k.rateLimit.requestsPerDay * 0.8),
    recommendations: []
  };
  
  optimization.underutilized.forEach(key => {
    optimization.recommendations.push({
      type: 'reduce_limits',
      keyId: key.id,
      message: `Consider reducing rate limits for "${key.name}"`,
      currentLimit: key.rateLimit.requestsPerDay,
      suggestedLimit: Math.ceil(key.usage.totalRequests * 1.2)
    });
  });
  
  optimization.overutilized.forEach(key => {
    optimization.recommendations.push({
      type: 'increase_limits',
      keyId: key.id,
      message: `Consider increasing rate limits for "${key.name}"`,
      currentLimit: key.rateLimit.requestsPerDay,
      suggestedLimit: Math.ceil(key.usage.totalRequests * 1.5)
    });
  });
  
  return optimization;
}

​
Troubleshooting

​
”No API keys found”

Cause: No API keys match the criteria or account has no keys. Solution:
  • Remove restrictive filters
  • Check if you have created any API keys
  • Verify your account has API key creation permissions

​
”Invalid status filter”

Cause: Unsupported status value. Solution:
  • Use supported statuses: active, inactive, expired, revoked, all
  • Check for typos

​
”Invalid permission filter”

Cause: Unsupported permission value. Solution:
  • Use supported permissions: identity, scores, achievements, trading, trust, attestations, all
  • Check for typos

​
Rate Limits

API key listing requests are subject to rate limits:
  • Free tier: 60 requests per minute
  • Starter tier: 300 requests per minute
  • Professional tier: 1,000 requests per minute
  • Enterprise tier: Custom limits
Implement caching to reduce API calls.