Create API Key

Create API Key

curl --request POST \
  --url https://api-mainnet.onzks.com/v1/developer/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "permissions": [
    {
      "permissions[].resource": "<string>",
      "permissions[].actions": [
        {}
      ],
      "permissions[].restrictions": {
        "permissions[].restrictions.identities": [
          {}
        ],
        "permissions[].restrictions.chains": [
          {}
        ],
        "permissions[].restrictions.ipWhitelist": [
          {}
        ]
      }
    }
  ],
  "rateLimit": {
    "rateLimit.requestsPerMinute": 123,
    "rateLimit.requestsPerHour": 123,
    "rateLimit.requestsPerDay": 123,
    "rateLimit.burstLimit": 123
  },
  "expiry": "<string>",
  "webhooks": [
    {
      "webhooks[].url": "<string>",
      "webhooks[].events": [
        {}
      ],
      "webhooks[].secret": "<string>"
    }
  ],
  "metadata": {}
}
'

import requests

url = "https://api-mainnet.onzks.com/v1/developer/keys"

payload = {
    "name": "<string>",
    "description": "<string>",
    "permissions": [
        {
            "permissions[].resource": "<string>",
            "permissions[].actions": [{}],
            "permissions[].restrictions": {
                "permissions[].restrictions.identities": [{}],
                "permissions[].restrictions.chains": [{}],
                "permissions[].restrictions.ipWhitelist": [{}]
            }
        }
    ],
    "rateLimit": {
        "rateLimit.requestsPerMinute": 123,
        "rateLimit.requestsPerHour": 123,
        "rateLimit.requestsPerDay": 123,
        "rateLimit.burstLimit": 123
    },
    "expiry": "<string>",
    "webhooks": [
        {
            "webhooks[].url": "<string>",
            "webhooks[].events": [{}],
            "webhooks[].secret": "<string>"
        }
    ],
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    permissions: [
      {
        'permissions[].resource': '<string>',
        'permissions[].actions': [{}],
        'permissions[].restrictions': {
          'permissions[].restrictions.identities': [{}],
          'permissions[].restrictions.chains': [{}],
          'permissions[].restrictions.ipWhitelist': [{}]
        }
      }
    ],
    rateLimit: {
      'rateLimit.requestsPerMinute': 123,
      'rateLimit.requestsPerHour': 123,
      'rateLimit.requestsPerDay': 123,
      'rateLimit.burstLimit': 123
    },
    expiry: '<string>',
    webhooks: [
      {
        'webhooks[].url': '<string>',
        'webhooks[].events': [{}],
        'webhooks[].secret': '<string>'
      }
    ],
    metadata: {}
  })
};

fetch('https://api-mainnet.onzks.com/v1/developer/keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-mainnet.onzks.com/v1/developer/keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'permissions' => [
        [
                'permissions[].resource' => '<string>',
                'permissions[].actions' => [
                                [
                                                                
                                ]
                ],
                'permissions[].restrictions' => [
                                'permissions[].restrictions.identities' => [
                                                                [
                                                                                                                                
                                                                ]
                                ],
                                'permissions[].restrictions.chains' => [
                                                                [
                                                                                                                                
                                                                ]
                                ],
                                'permissions[].restrictions.ipWhitelist' => [
                                                                [
                                                                                                                                
                                                                ]
                                ]
                ]
        ]
    ],
    'rateLimit' => [
        'rateLimit.requestsPerMinute' => 123,
        'rateLimit.requestsPerHour' => 123,
        'rateLimit.requestsPerDay' => 123,
        'rateLimit.burstLimit' => 123
    ],
    'expiry' => '<string>',
    'webhooks' => [
        [
                'webhooks[].url' => '<string>',
                'webhooks[].events' => [
                                [
                                                                
                                ]
                ],
                'webhooks[].secret' => '<string>'
        ]
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-mainnet.onzks.com/v1/developer/keys"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"permissions\": [\n    {\n      \"permissions[].resource\": \"<string>\",\n      \"permissions[].actions\": [\n        {}\n      ],\n      \"permissions[].restrictions\": {\n        \"permissions[].restrictions.identities\": [\n          {}\n        ],\n        \"permissions[].restrictions.chains\": [\n          {}\n        ],\n        \"permissions[].restrictions.ipWhitelist\": [\n          {}\n        ]\n      }\n    }\n  ],\n  \"rateLimit\": {\n    \"rateLimit.requestsPerMinute\": 123,\n    \"rateLimit.requestsPerHour\": 123,\n    \"rateLimit.requestsPerDay\": 123,\n    \"rateLimit.burstLimit\": 123\n  },\n  \"expiry\": \"<string>\",\n  \"webhooks\": [\n    {\n      \"webhooks[].url\": \"<string>\",\n      \"webhooks[].events\": [\n        {}\n      ],\n      \"webhooks[].secret\": \"<string>\"\n    }\n  ],\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-mainnet.onzks.com/v1/developer/keys")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"permissions\": [\n    {\n      \"permissions[].resource\": \"<string>\",\n      \"permissions[].actions\": [\n        {}\n      ],\n      \"permissions[].restrictions\": {\n        \"permissions[].restrictions.identities\": [\n          {}\n        ],\n        \"permissions[].restrictions.chains\": [\n          {}\n        ],\n        \"permissions[].restrictions.ipWhitelist\": [\n          {}\n        ]\n      }\n    }\n  ],\n  \"rateLimit\": {\n    \"rateLimit.requestsPerMinute\": 123,\n    \"rateLimit.requestsPerHour\": 123,\n    \"rateLimit.requestsPerDay\": 123,\n    \"rateLimit.burstLimit\": 123\n  },\n  \"expiry\": \"<string>\",\n  \"webhooks\": [\n    {\n      \"webhooks[].url\": \"<string>\",\n      \"webhooks[].events\": [\n        {}\n      ],\n      \"webhooks[].secret\": \"<string>\"\n    }\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/developer/keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"permissions\": [\n    {\n      \"permissions[].resource\": \"<string>\",\n      \"permissions[].actions\": [\n        {}\n      ],\n      \"permissions[].restrictions\": {\n        \"permissions[].restrictions.identities\": [\n          {}\n        ],\n        \"permissions[].restrictions.chains\": [\n          {}\n        ],\n        \"permissions[].restrictions.ipWhitelist\": [\n          {}\n        ]\n      }\n    }\n  ],\n  \"rateLimit\": {\n    \"rateLimit.requestsPerMinute\": 123,\n    \"rateLimit.requestsPerHour\": 123,\n    \"rateLimit.requestsPerDay\": 123,\n    \"rateLimit.burstLimit\": 123\n  },\n  \"expiry\": \"<string>\",\n  \"webhooks\": [\n    {\n      \"webhooks[].url\": \"<string>\",\n      \"webhooks[].events\": [\n        {}\n      ],\n      \"webhooks[].secret\": \"<string>\"\n    }\n  ],\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "apiKey": "<string>",
  "keyId": "<string>",
  "key": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "permissions": [
      {}
    ],
    "rateLimit": {},
    "status": "<string>",
    "createdAt": "<string>",
    "expiry": "<string>",
    "lastUsed": "<string>",
    "usage": {
      "totalRequests": 123,
      "requestsToday": 123,
      "requestsThisMonth": 123
    }
  },
  "webhooks": [
    {}
  ],
  "timestamp": "<string>"
}

POST

developer

keys

Create API Key

curl --request POST \
  --url https://api-mainnet.onzks.com/v1/developer/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "permissions": [
    {
      "permissions[].resource": "<string>",
      "permissions[].actions": [
        {}
      ],
      "permissions[].restrictions": {
        "permissions[].restrictions.identities": [
          {}
        ],
        "permissions[].restrictions.chains": [
          {}
        ],
        "permissions[].restrictions.ipWhitelist": [
          {}
        ]
      }
    }
  ],
  "rateLimit": {
    "rateLimit.requestsPerMinute": 123,
    "rateLimit.requestsPerHour": 123,
    "rateLimit.requestsPerDay": 123,
    "rateLimit.burstLimit": 123
  },
  "expiry": "<string>",
  "webhooks": [
    {
      "webhooks[].url": "<string>",
      "webhooks[].events": [
        {}
      ],
      "webhooks[].secret": "<string>"
    }
  ],
  "metadata": {}
}
'

import requests

url = "https://api-mainnet.onzks.com/v1/developer/keys"

payload = {
    "name": "<string>",
    "description": "<string>",
    "permissions": [
        {
            "permissions[].resource": "<string>",
            "permissions[].actions": [{}],
            "permissions[].restrictions": {
                "permissions[].restrictions.identities": [{}],
                "permissions[].restrictions.chains": [{}],
                "permissions[].restrictions.ipWhitelist": [{}]
            }
        }
    ],
    "rateLimit": {
        "rateLimit.requestsPerMinute": 123,
        "rateLimit.requestsPerHour": 123,
        "rateLimit.requestsPerDay": 123,
        "rateLimit.burstLimit": 123
    },
    "expiry": "<string>",
    "webhooks": [
        {
            "webhooks[].url": "<string>",
            "webhooks[].events": [{}],
            "webhooks[].secret": "<string>"
        }
    ],
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    permissions: [
      {
        'permissions[].resource': '<string>',
        'permissions[].actions': [{}],
        'permissions[].restrictions': {
          'permissions[].restrictions.identities': [{}],
          'permissions[].restrictions.chains': [{}],
          'permissions[].restrictions.ipWhitelist': [{}]
        }
      }
    ],
    rateLimit: {
      'rateLimit.requestsPerMinute': 123,
      'rateLimit.requestsPerHour': 123,
      'rateLimit.requestsPerDay': 123,
      'rateLimit.burstLimit': 123
    },
    expiry: '<string>',
    webhooks: [
      {
        'webhooks[].url': '<string>',
        'webhooks[].events': [{}],
        'webhooks[].secret': '<string>'
      }
    ],
    metadata: {}
  })
};

fetch('https://api-mainnet.onzks.com/v1/developer/keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-mainnet.onzks.com/v1/developer/keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'permissions' => [
        [
                'permissions[].resource' => '<string>',
                'permissions[].actions' => [
                                [
                                                                
                                ]
                ],
                'permissions[].restrictions' => [
                                'permissions[].restrictions.identities' => [
                                                                [
                                                                                                                                
                                                                ]
                                ],
                                'permissions[].restrictions.chains' => [
                                                                [
                                                                                                                                
                                                                ]
                                ],
                                'permissions[].restrictions.ipWhitelist' => [
                                                                [
                                                                                                                                
                                                                ]
                                ]
                ]
        ]
    ],
    'rateLimit' => [
        'rateLimit.requestsPerMinute' => 123,
        'rateLimit.requestsPerHour' => 123,
        'rateLimit.requestsPerDay' => 123,
        'rateLimit.burstLimit' => 123
    ],
    'expiry' => '<string>',
    'webhooks' => [
        [
                'webhooks[].url' => '<string>',
                'webhooks[].events' => [
                                [
                                                                
                                ]
                ],
                'webhooks[].secret' => '<string>'
        ]
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-mainnet.onzks.com/v1/developer/keys"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"permissions\": [\n    {\n      \"permissions[].resource\": \"<string>\",\n      \"permissions[].actions\": [\n        {}\n      ],\n      \"permissions[].restrictions\": {\n        \"permissions[].restrictions.identities\": [\n          {}\n        ],\n        \"permissions[].restrictions.chains\": [\n          {}\n        ],\n        \"permissions[].restrictions.ipWhitelist\": [\n          {}\n        ]\n      }\n    }\n  ],\n  \"rateLimit\": {\n    \"rateLimit.requestsPerMinute\": 123,\n    \"rateLimit.requestsPerHour\": 123,\n    \"rateLimit.requestsPerDay\": 123,\n    \"rateLimit.burstLimit\": 123\n  },\n  \"expiry\": \"<string>\",\n  \"webhooks\": [\n    {\n      \"webhooks[].url\": \"<string>\",\n      \"webhooks[].events\": [\n        {}\n      ],\n      \"webhooks[].secret\": \"<string>\"\n    }\n  ],\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-mainnet.onzks.com/v1/developer/keys")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"permissions\": [\n    {\n      \"permissions[].resource\": \"<string>\",\n      \"permissions[].actions\": [\n        {}\n      ],\n      \"permissions[].restrictions\": {\n        \"permissions[].restrictions.identities\": [\n          {}\n        ],\n        \"permissions[].restrictions.chains\": [\n          {}\n        ],\n        \"permissions[].restrictions.ipWhitelist\": [\n          {}\n        ]\n      }\n    }\n  ],\n  \"rateLimit\": {\n    \"rateLimit.requestsPerMinute\": 123,\n    \"rateLimit.requestsPerHour\": 123,\n    \"rateLimit.requestsPerDay\": 123,\n    \"rateLimit.burstLimit\": 123\n  },\n  \"expiry\": \"<string>\",\n  \"webhooks\": [\n    {\n      \"webhooks[].url\": \"<string>\",\n      \"webhooks[].events\": [\n        {}\n      ],\n      \"webhooks[].secret\": \"<string>\"\n    }\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/developer/keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"permissions\": [\n    {\n      \"permissions[].resource\": \"<string>\",\n      \"permissions[].actions\": [\n        {}\n      ],\n      \"permissions[].restrictions\": {\n        \"permissions[].restrictions.identities\": [\n          {}\n        ],\n        \"permissions[].restrictions.chains\": [\n          {}\n        ],\n        \"permissions[].restrictions.ipWhitelist\": [\n          {}\n        ]\n      }\n    }\n  ],\n  \"rateLimit\": {\n    \"rateLimit.requestsPerMinute\": 123,\n    \"rateLimit.requestsPerHour\": 123,\n    \"rateLimit.requestsPerDay\": 123,\n    \"rateLimit.burstLimit\": 123\n  },\n  \"expiry\": \"<string>\",\n  \"webhooks\": [\n    {\n      \"webhooks[].url\": \"<string>\",\n      \"webhooks[].events\": [\n        {}\n      ],\n      \"webhooks[].secret\": \"<string>\"\n    }\n  ],\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "apiKey": "<string>",
  "keyId": "<string>",
  "key": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "permissions": [
      {}
    ],
    "rateLimit": {},
    "status": "<string>",
    "createdAt": "<string>",
    "expiry": "<string>",
    "lastUsed": "<string>",
    "usage": {
      "totalRequests": 123,
      "requestsToday": 123,
      "requestsThisMonth": 123
    }
  },
  "webhooks": [
    {}
  ],
  "timestamp": "<string>"
}

Overview

Create a new API key with specific permissions and rate limits for accessing the ZKScore API. This endpoint allows developers to generate secure API keys that can be used to authenticate requests and access platform features.

Use this endpoint to create API keys for your applications. Store the API key securely and never expose it in client-side code. Use environment variables or secure key management systems.

Parameters

string

required

Human-readable name for the API key

Choose a descriptive name that helps identify the key’s purpose (e.g., “Production App”, “Development Testing”)

string

Optional description of the API key’s intended use

array

required

Array of permissions for the API key

Show available permissions

string

Resource type

identity - Identity management
scores - Score queries
achievements - Achievement operations
trading - Trading data
trust - Trust layer operations
attestations - Attestation management
all - All resources

array

Allowed actions

read - Read operations
write - Write operations
delete - Delete operations
all - All actions

object

Optional restrictions

Show restriction properties

array

Specific identities the key can access

array

Specific blockchain networks

array

Allowed IP addresses

object

Rate limiting configuration

Show rateLimit properties

number

Maximum requests per minute (default: 60)

number

Maximum requests per hour (default: 1000)

number

Maximum requests per day (default: 10000)

number

Burst limit for short-term spikes (default: 100)

string

ISO 8601 timestamp when the API key expires (optional)

array

Webhook configurations

Show webhook properties

string

Webhook endpoint URL

array

Events to subscribe to

string

Webhook secret for verification

object

Additional metadata for the API key

Response

boolean

Indicates if the API key was created successfully

string

The generated API key (only shown once)

Store this API key securely. It will not be shown again and cannot be recovered if lost.

string

Unique identifier for the API key

object

API key details

Show key properties

string

API key identifier

string

API key name

string

API key description

array

API key permissions

object

Rate limiting configuration

string

API key status (active, inactive, expired, revoked)

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of expiry (if set)

string

ISO 8601 timestamp of last use (null if never used)

object

Usage statistics

Show usage properties

number

Total requests made

number

Requests made today

number

Requests made this month

array

Configured webhooks

string

ISO 8601 timestamp of the response

Examples

curl -X POST "https://api.onzks.com/v1/developer/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production App",
    "description": "API key for production application",
    "permissions": [
      {
        "resource": "scores",
        "actions": ["read"]
      },
      {
        "resource": "identity",
        "actions": ["read"]
      }
    ],
    "rateLimit": {
      "requestsPerMinute": 100,
      "requestsPerHour": 1000,
      "requestsPerDay": 10000
    }
  }'

curl -X POST "https://api.onzks.com/v1/developer/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin Dashboard",
    "description": "Full access API key for admin dashboard",
    "permissions": [
      {
        "resource": "all",
        "actions": ["all"]
      }
    ],
    "rateLimit": {
      "requestsPerMinute": 500,
      "requestsPerHour": 5000,
      "requestsPerDay": 50000
    },
    "expiry": "2025-01-20T15:45:00Z",
    "webhooks": [
      {
        "url": "https://myapp.com/webhooks/zkscore",
        "events": ["score.updated", "achievement.earned"],
        "secret": "webhook_secret_123"
      }
    ]
  }'

curl -X POST "https://api.onzks.com/v1/developer/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Access Key",
    "description": "API key with restricted access",
    "permissions": [
      {
        "resource": "scores",
        "actions": ["read"],
        "restrictions": {
          "identities": ["alice.zks", "bob.zks"],
          "chains": [1, 137]
        }
      }
    ],
    "rateLimit": {
      "requestsPerMinute": 10,
      "requestsPerHour": 100,
      "requestsPerDay": 1000
    }
  }'

async function createApiKey(keyData) {
  const {
    name,
    description,
    permissions,
    rateLimit = {
      requestsPerMinute: 60,
      requestsPerHour: 1000,
      requestsPerDay: 10000
    },
    expiry,
    webhooks = [],
    metadata = {}
  } = keyData;

  const requestBody = {
    name,
    description,
    permissions,
    rateLimit,
    webhooks,
    metadata
  };

  if (expiry) {
    requestBody.expiry = expiry;
  }

  const response = await fetch('https://api.onzks.com/v1/developer/keys', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
  });

  const result = await response.json();

  if (result.success) {
    console.log(`✅ API Key created: ${result.keyId}`);
    console.log(`API Key: ${result.apiKey}`);
    console.log(`Status: ${result.key.status}`);
    console.log(`Rate Limit: ${result.key.rateLimit.requestsPerMinute} req/min`);
    
    // Store the API key securely
    await storeApiKeySecurely(result.apiKey, result.keyId);
  } else {
    console.error('Failed to create API key:', result.message);
  }

  return result;
}

// Usage examples
await createApiKey({
  name: 'Production App',
  description: 'API key for production application',
  permissions: [
    {
      resource: 'scores',
      actions: ['read']
    },
    {
      resource: 'identity',
      actions: ['read']
    }
  ],
  rateLimit: {
    requestsPerMinute: 100,
    requestsPerHour: 1000,
    requestsPerDay: 10000
  }
});

// Full permissions example
await createApiKey({
  name: 'Admin Dashboard',
  description: 'Full access API key for admin dashboard',
  permissions: [
    {
      resource: 'all',
      actions: ['all']
    }
  ],
  rateLimit: {
    requestsPerMinute: 500,
    requestsPerHour: 5000,
    requestsPerDay: 50000
  },
  expiry: '2025-01-20T15:45:00Z',
  webhooks: [
    {
      url: 'https://myapp.com/webhooks/zkscore',
      events: ['score.updated', 'achievement.earned'],
      secret: 'webhook_secret_123'
    }
  ]
});

import requests
import json
from datetime import datetime, timedelta

def create_api_key(name, description=None, permissions=None, rate_limit=None, 
                  expiry=None, webhooks=None, metadata=None):
    if permissions is None:
        permissions = []
    if rate_limit is None:
        rate_limit = {
            'requestsPerMinute': 60,
            'requestsPerHour': 1000,
            'requestsPerDay': 10000
        }
    if webhooks is None:
        webhooks = []
    if metadata is None:
        metadata = {}
    
    request_body = {
        'name': name,
        'description': description,
        'permissions': permissions,
        'rateLimit': rate_limit,
        'webhooks': webhooks,
        'metadata': metadata
    }
    
    if expiry:
        request_body['expiry'] = expiry
    
    response = requests.post(
        'https://api.onzks.com/v1/developer/keys',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json=request_body
    )
    
    result = response.json()
    
    if result['success']:
        print(f"✅ API Key created: {result['keyId']}")
        print(f"API Key: {result['apiKey']}")
        print(f"Status: {result['key']['status']}")
        print(f"Rate Limit: {result['key']['rateLimit']['requestsPerMinute']} req/min")
        
        # Store the API key securely
        store_api_key_securely(result['apiKey'], result['keyId'])
    else:
        print(f"Failed to create API key: {result['message']}")
    
    return result

# Usage examples
create_api_key(
    name='Production App',
    description='API key for production application',
    permissions=[
        {
            'resource': 'scores',
            'actions': ['read']
        },
        {
            'resource': 'identity',
            'actions': ['read']
        }
    ],
    rate_limit={
        'requestsPerMinute': 100,
        'requestsPerHour': 1000,
        'requestsPerDay': 10000
    }
)

# Full permissions example
create_api_key(
    name='Admin Dashboard',
    description='Full access API key for admin dashboard',
    permissions=[
        {
            'resource': 'all',
            'actions': ['all']
        }
    ],
    rate_limit={
        'requestsPerMinute': 500,
        'requestsPerHour': 5000,
        'requestsPerDay': 50000
    },
    expiry='2025-01-20T15:45:00Z',
    webhooks=[
        {
            'url': 'https://myapp.com/webhooks/zkscore',
            'events': ['score.updated', 'achievement.earned'],
            'secret': 'webhook_secret_123'
        }
    ]
)

Response Example

{
  "success": true,
  "apiKey": "zk_live_1234567890abcdef1234567890abcdef12345678",
  "keyId": "key_1234567890abcdef",
  "key": {
    "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-20T15:45:00Z",
    "expiry": null,
    "lastUsed": null,
    "usage": {
      "totalRequests": 0,
      "requestsToday": 0,
      "requestsThisMonth": 0
    }
  },
  "webhooks": [],
  "timestamp": "2024-01-20T15:45:00Z"
}

Use Cases

1. Application API Keys

Create API keys for different applications:

async function createApplicationKeys() {
  const applications = [
    {
      name: 'Web Dashboard',
      description: 'API key for web dashboard',
      permissions: [
        { resource: 'scores', actions: ['read'] },
        { resource: 'identity', actions: ['read'] },
        { resource: 'achievements', actions: ['read'] }
      ],
      rateLimit: {
        requestsPerMinute: 200,
        requestsPerHour: 2000,
        requestsPerDay: 20000
      }
    },
    {
      name: 'Mobile App',
      description: 'API key for mobile application',
      permissions: [
        { resource: 'scores', actions: ['read'] },
        { resource: 'identity', actions: ['read'] }
      ],
      rateLimit: {
        requestsPerMinute: 100,
        requestsPerHour: 1000,
        requestsPerDay: 10000
      }
    },
    {
      name: 'Backend Service',
      description: 'API key for backend service',
      permissions: [
        { resource: 'all', actions: ['all'] }
      ],
      rateLimit: {
        requestsPerMinute: 500,
        requestsPerHour: 5000,
        requestsPerDay: 50000
      }
    }
  ];

  const results = [];
  
  for (const app of applications) {
    try {
      const result = await createApiKey(app);
      results.push({ app: app.name, success: true, keyId: result.keyId });
    } catch (error) {
      results.push({ app: app.name, success: false, error: error.message });
    }
  }
  
  return results;
}

2. Environment-Specific Keys

Create keys for different environments:

async function createEnvironmentKeys() {
  const environments = {
    development: {
      name: 'Development Environment',
      description: 'API key for development testing',
      permissions: [
        { resource: 'all', actions: ['all'] }
      ],
      rateLimit: {
        requestsPerMinute: 50,
        requestsPerHour: 500,
        requestsPerDay: 5000
      },
      expiry: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString() // 30 days
    },
    staging: {
      name: 'Staging Environment',
      description: 'API key for staging environment',
      permissions: [
        { resource: 'all', actions: ['all'] }
      ],
      rateLimit: {
        requestsPerMinute: 100,
        requestsPerHour: 1000,
        requestsPerDay: 10000
      },
      expiry: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString() // 90 days
    },
    production: {
      name: 'Production Environment',
      description: 'API key for production environment',
      permissions: [
        { resource: 'all', actions: ['all'] }
      ],
      rateLimit: {
        requestsPerMinute: 1000,
        requestsPerHour: 10000,
        requestsPerDay: 100000
      }
    }
  };

  const results = {};
  
  for (const [env, config] of Object.entries(environments)) {
    try {
      const result = await createApiKey(config);
      results[env] = { success: true, keyId: result.keyId };
    } catch (error) {
      results[env] = { success: false, error: error.message };
    }
  }
  
  return results;
}

3. Restricted Access Keys

Create keys with specific restrictions:

async function createRestrictedKeys() {
  const restrictedKeys = [
    {
      name: 'Read-Only Analytics',
      description: 'Read-only access for analytics',
      permissions: [
        {
          resource: 'scores',
          actions: ['read'],
          restrictions: {
            chains: [1, 137] // Ethereum and Polygon only
          }
        }
      ],
      rateLimit: {
        requestsPerMinute: 50,
        requestsPerHour: 500,
        requestsPerDay: 5000
      }
    },
    {
      name: 'Specific User Access',
      description: 'Access limited to specific users',
      permissions: [
        {
          resource: 'scores',
          actions: ['read'],
          restrictions: {
            identities: ['alice.zks', 'bob.zks', 'charlie.zks']
          }
        }
      ],
      rateLimit: {
        requestsPerMinute: 20,
        requestsPerHour: 200,
        requestsPerDay: 2000
      }
    },
    {
      name: 'IP-Whitelisted Access',
      description: 'Access limited to specific IP addresses',
      permissions: [
        {
          resource: 'all',
          actions: ['all'],
          restrictions: {
            ipWhitelist: ['192.168.1.0/24', '10.0.0.0/8']
          }
        }
      ],
      rateLimit: {
        requestsPerMinute: 200,
        requestsPerHour: 2000,
        requestsPerDay: 20000
      }
    }
  ];

  const results = [];
  
  for (const keyConfig of restrictedKeys) {
    try {
      const result = await createApiKey(keyConfig);
      results.push({ name: keyConfig.name, success: true, keyId: result.keyId });
    } catch (error) {
      results.push({ name: keyConfig.name, success: false, error: error.message });
    }
  }
  
  return results;
}

4. Webhook Integration

Create keys with webhook configurations:

async function createWebhookKeys() {
  const webhookConfig = {
    name: 'Webhook Integration',
    description: 'API key with webhook support',
    permissions: [
      { resource: 'all', actions: ['all'] }
    ],
    rateLimit: {
      requestsPerMinute: 100,
      requestsPerHour: 1000,
      requestsPerDay: 10000
    },
    webhooks: [
      {
        url: 'https://myapp.com/webhooks/zkscore/scores',
        events: ['score.updated', 'score.calculated'],
        secret: 'webhook_secret_scores_123'
      },
      {
        url: 'https://myapp.com/webhooks/zkscore/achievements',
        events: ['achievement.earned', 'achievement.claimed'],
        secret: 'webhook_secret_achievements_123'
      },
      {
        url: 'https://myapp.com/webhooks/zkscore/attestations',
        events: ['attestation.created', 'attestation.revoked'],
        secret: 'webhook_secret_attestations_123'
      }
    ]
  };

  return await createApiKey(webhookConfig);
}

5. Batch Key Creation

Create multiple keys at once:

async function createBatchKeys(keyConfigs) {
  const results = [];
  
  for (const config of keyConfigs) {
    try {
      const result = await createApiKey(config);
      results.push({ 
        name: config.name, 
        success: true, 
        keyId: result.keyId,
        apiKey: result.apiKey
      });
    } catch (error) {
      results.push({ 
        name: config.name, 
        success: false, 
        error: error.message 
      });
    }
  }
  
  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);
  
  console.log(`Successfully created ${successful.length} API keys`);
  if (failed.length > 0) {
    console.log(`Failed to create ${failed.length} API keys`);
  }
  
  return results;
}

Best Practices

1. Security

Implement secure API key management:

async function storeApiKeySecurely(apiKey, keyId) {
  // Store in secure environment variables
  process.env.ZKSCORE_API_KEY = apiKey;
  process.env.ZKSCORE_KEY_ID = keyId;
  
  // Or store in secure key management system
  await keyManagementSystem.store({
    keyId,
    apiKey,
    encrypted: true
  });
}

function getApiKey() {
  return process.env.ZKSCORE_API_KEY;
}

2. Rate Limiting

Handle rate limits appropriately:

class RateLimiter {
  constructor(limits) {
    this.limits = limits;
    this.requests = [];
  }
  
  async checkLimit() {
    const now = Date.now();
    const oneMinute = 60 * 1000;
    const oneHour = 60 * 60 * 1000;
    const oneDay = 24 * 60 * 60 * 1000;
    
    // Remove old requests
    this.requests = this.requests.filter(time => now - time < oneDay);
    
    // Check limits
    const recentRequests = this.requests.filter(time => now - time < oneMinute);
    const hourlyRequests = this.requests.filter(time => now - time < oneHour);
    const dailyRequests = this.requests.length;
    
    if (recentRequests.length >= this.limits.requestsPerMinute) {
      throw new Error('Rate limit exceeded: requests per minute');
    }
    
    if (hourlyRequests.length >= this.limits.requestsPerHour) {
      throw new Error('Rate limit exceeded: requests per hour');
    }
    
    if (dailyRequests >= this.limits.requestsPerDay) {
      throw new Error('Rate limit exceeded: requests per day');
    }
    
    this.requests.push(now);
  }
}

3. Key Rotation

Implement key rotation:

async function rotateApiKey(keyId) {
  // Create new key
  const newKey = await createApiKey({
    name: 'Rotated Key',
    description: 'Key created during rotation',
    permissions: [
      { resource: 'all', actions: ['all'] }
    ]
  });
  
  // Revoke old key
  await revokeApiKey(keyId);
  
  return newKey;
}

4. Monitoring

Monitor API key usage:

async function monitorApiKeyUsage(keyId) {
  const usage = await getApiKeyUsage(keyId);
  
  const alerts = [];
  
  if (usage.requestsToday > usage.limits.requestsPerDay * 0.8) {
    alerts.push('Daily limit approaching');
  }
  
  if (usage.requestsThisHour > usage.limits.requestsPerHour * 0.9) {
    alerts.push('Hourly limit approaching');
  }
  
  if (usage.lastUsed && Date.now() - new Date(usage.lastUsed) > 7 * 24 * 60 * 60 * 1000) {
    alerts.push('Key not used in 7 days');
  }
  
  return { usage, alerts };
}

List API Keys - View all API keys
Revoke API Key - Revoke an API key
Get Usage - View API key usage

Troubleshooting

”Invalid permissions”

Cause: Invalid permission configuration. Solution:

Use supported resources: identity, scores, achievements, trading, trust, attestations, all
Use supported actions: read, write, delete, all
Check permission structure

”Rate limit too high”

Cause: Requested rate limits exceed your plan limits. Solution:

Check your plan’s rate limits
Reduce requested limits
Upgrade your plan if needed

”Invalid webhook URL”

Cause: Webhook URL is invalid or unreachable. Solution:

Ensure webhook URL is accessible
Check URL format
Verify webhook endpoint is working

”API key already exists”

Cause: API key with same name already exists. Solution:

Use a different name
Check existing keys
Use unique identifiers

Rate Limits

API key creation requests are subject to rate limits:

Free tier: 5 keys per day
Starter tier: 20 keys per day
Professional tier: 100 keys per day
Enterprise tier: Custom limits

Implement key rotation to manage key lifecycle.

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Application API Keys

2. Environment-Specific Keys

3. Restricted Access Keys

4. Webhook Integration

5. Batch Key Creation

Best Practices

1. Security

2. Rate Limiting

3. Key Rotation

4. Monitoring

Troubleshooting

”Invalid permissions”

”Rate limit too high”

”Invalid webhook URL”

”API key already exists”

Rate Limits

​Overview

​Parameters

​Response

​Examples

​Response Example

​Use Cases

​1. Application API Keys

​2. Environment-Specific Keys

​3. Restricted Access Keys

​4. Webhook Integration

​5. Batch Key Creation

​Best Practices

​1. Security

​2. Rate Limiting

​3. Key Rotation

​4. Monitoring

​Related Endpoints

​Troubleshooting

​”Invalid permissions”

​”Rate limit too high”

​”Invalid webhook URL”

​”API key already exists”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Application API Keys

2. Environment-Specific Keys

3. Restricted Access Keys

4. Webhook Integration

5. Batch Key Creation

Best Practices

1. Security

2. Rate Limiting

3. Key Rotation

4. Monitoring

Related Endpoints

Troubleshooting

”Invalid permissions”

”Rate limit too high”

”Invalid webhook URL”

”API key already exists”

Rate Limits