Authentication

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

Visit the Developer Portal
Connect your wallet
Navigate to “API Keys”
Click “Create New API Key”
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"

const response = await fetch('https://api-mainnet.onzks.com/api/v1/scores/0x...', {
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

import requests

headers = {
    'Authorization': f'Bearer {YOUR_API_KEY}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api-mainnet.onzks.com/api/v1/scores/0x...',
    headers=headers
)

API Key Permissions

API keys can have different permission levels:

Permission	Description
`read`	Read-only access to public data
`write`	Create and update resources
`admin`	Full access including deletions

Use the minimum required permissions for your use case to enhance security.

Security Best Practices

Never Expose Keys Client-Side

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

Use 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 Keys Regularly

Rotate your API keys periodically and immediately if compromised:

Create a new API key
Update your application
Revoke the old key

Use Different Keys for Different Environments

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

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

API Key Authentication

Getting an API Key

Making Authenticated Requests

Example Requests

API Key Permissions

Security Best Practices

Error Responses

401 Unauthorized

403 Forbidden

Managing API Keys

Create a New Key

List Your Keys

Revoke a Key

Developer API Reference

Next Steps

Make Your First Request

Explore API Endpoints

​API Key Authentication

​Getting an API Key

​Making Authenticated Requests

​Example Requests

​API Key Permissions

​Security Best Practices

​Error Responses

​401 Unauthorized

​403 Forbidden

​Managing API Keys

​Create a New Key

​List Your Keys

​Revoke a Key

Developer API Reference

​Next Steps

Make Your First Request

Explore API Endpoints

API Key Authentication

Getting an API Key

Making Authenticated Requests

Example Requests

API Key Permissions

Security Best Practices

Error Responses

401 Unauthorized

403 Forbidden

Managing API Keys

Create a New Key

List Your Keys

Revoke a Key

Next Steps