Skip to main content

​
API Key Authentication

ZKScore API uses Bearer token authentication. All API requests must include your API key in the Authorization header.

​
Getting an API Key

  1. Visit the Developer Portal
  2. Connect your wallet
  3. Navigate to “API Keys”
  4. Click “Create New API Key”
  5. Copy and securely store your key
Your API key is shown only once. Store it securely and never expose it in client-side code.

​
Making Authenticated Requests

Include your API key in the Authorization header with the Bearer scheme: 
Authorization: Bearer YOUR_API_KEY

​
Example Requests

curl https://api-mainnet.onzks.com/api/v1/scores/0x... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
API Key Permissions

API keys can have different permission levels:
PermissionDescription
readRead-only access to public data
writeCreate and update resources
adminFull access including deletions
Use the minimum required permissions for your use case to enhance security.

​
Security Best Practices

Always make API calls from your backend server. Never include API keys in:
  • Frontend JavaScript code
  • Mobile app code
  • Public repositories
  • Client-side environment variables
Store API keys in environment variables, not in your code:
.env
ZKSCORE_API_KEY=your_api_key_here

const apiKey = process.env.ZKSCORE_API_KEY;
Rotate your API keys periodically and immediately if compromised:
  1. Create a new API key
  2. Update your application
  3. Revoke the old key
Create separate API keys for development, staging, and production:
  • dev-app-name
  • staging-app-name
  • prod-app-name

​
Error Responses

​
401 Unauthorized

Missing or invalid API key: 
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "timestamp": "2025-10-22T10:30:00Z"
}

​
403 Forbidden

Insufficient permissions: 
{
  "success": false,
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this operation",
  "timestamp": "2025-10-22T10:30:00Z"
}

​
Managing API Keys

​
Create a New Key

POST /api/v1/developer/keys

{
  "name": "My Application",
  "permissions": ["read"],
  "rateLimit": 100
}

​
List Your Keys

GET /api/v1/developer/keys

​
Revoke a Key

DELETE /api/v1/developer/keys/:keyId

Developer API Reference

View complete API key management documentation

​
Next Steps

Make Your First Request

Follow the quick start guide

Explore API Endpoints

Browse all available endpoints