API Reference

API Keys

Create, list, and revoke API keys for programmatic access to the Minerva proof API.

API keys allow programmatic, long-lived access to the Minerva proof generation API — ideal for CI/CD pipelines, server-side integrations, batch proof workflows, and any automated process that does not involve a user session.

•Prefixed with mzk_ for easy identification in configs and secret vaults
•Generated with 256-bit entropy
•Stored argon2id-hashed at rest (raw key shown only once at creation)
•Scoped to your account (maximum 10 active keys per account)

Warning: Treat API keys like passwords. Store them in environment variables or CI/CD secret stores — never commit them to source control.

Creating an API Key

http

POST /api/v1/keys HTTP/1.1
Host: api.zkesg.com
Authorization: Bearer <your-session-token-or-api-key>
Content-Type: application/json

{
  "name": "ci-pipeline-prod",
  "description": "Used by GitHub Actions for nightly proof batch"
}

Field	Type	Required	Description
name	string	Yes	Human-readable label (max 64 chars, alphanumeric + hyphens)
description	string	No	Optional notes about the key's purpose

Response:

json

{
  "id": "key_01HX4KQZR9BNT5E2FPMCDVWJ3",
  "name": "ci-pipeline-prod",
  "description": "Used by GitHub Actions for nightly proof batch",
  "key": "mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5",
  "created_at": "2026-03-16T12:00:00Z",
  "last_used_at": null
}

Warning: The key field is shown only once. Copy it immediately and store it securely. It cannot be retrieved after this response.

Authenticating with an API Key

bash

# curl
curl -X POST https://api.zkesg.com/api/v1/proofs \
  -H "Authorization: Bearer $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "carbon_emissions",
    "inputs": { "scope1": 1240.5, "scope2": 870.2, "threshold": 2500 }
  }'

Listing Keys

http

GET /api/v1/keys HTTP/1.1
Host: api.zkesg.com
Authorization: Bearer <your-session-token-or-api-key>

json

{
  "keys": [
    {
      "id": "key_01HX4KQZR9BNT5E2FPMCDVWJ3",
      "name": "ci-pipeline-prod",
      "description": "Used by GitHub Actions for nightly proof batch",
      "created_at": "2026-03-16T12:00:00Z",
      "last_used_at": "2026-03-16T14:23:11Z"
    }
  ],
  "total": 1,
  "limit": 10
}

Revoking a Key

bash

curl -X DELETE "https://api.zkesg.com/api/v1/keys/key_01HX4KQZR9BNT5E2FPMCDVWJ3" \
  -H "Authorization: Bearer $MINERVA_API_KEY"

Revocation is permanent. Any subsequent requests using the revoked key return 401 Unauthorized.

Rate Limits

Limit	Value
API keys per account	10
Proof requests per minute (per key)	60
Proof requests per day (per account)	5,000
Batch proof size	100 proofs per request
Concurrent proof jobs	10

Error Reference

Status	Code	Meaning
401	invalid_api_key	Key is missing, malformed, or revoked
403	insufficient_scope	Key does not have permission for this operation
404	key_not_found	Key ID does not exist in your account
409	key_limit_reached	Account already has 10 active keys
429	rate_limit_exceeded	Too many requests — back off and retry

← Back to Documentation

Documentation

API Reference

API Keys

Create, list, and revoke API keys for programmatic access to the Minerva proof API.

•Prefixed with mzk_ for easy identification in configs and secret vaults
•Generated with 256-bit entropy
•Stored argon2id-hashed at rest (raw key shown only once at creation)
•Scoped to your account (maximum 10 active keys per account)

Warning: Treat API keys like passwords. Store them in environment variables or CI/CD secret stores — never commit them to source control.

Creating an API Key

http

POST /api/v1/keys HTTP/1.1
Host: api.zkesg.com
Authorization: Bearer <your-session-token-or-api-key>
Content-Type: application/json

{
  "name": "ci-pipeline-prod",
  "description": "Used by GitHub Actions for nightly proof batch"
}

Field	Type	Required	Description
name	string	Yes	Human-readable label (max 64 chars, alphanumeric + hyphens)
description	string	No	Optional notes about the key's purpose

Response:

json

{
  "id": "key_01HX4KQZR9BNT5E2FPMCDVWJ3",
  "name": "ci-pipeline-prod",
  "description": "Used by GitHub Actions for nightly proof batch",
  "key": "mzk_a7f3c2e9d1b84f6a2e0c5d8b3f7a1e4c9d2b5f8a3e6c1d4b7f0a3e6c9d2b5",
  "created_at": "2026-03-16T12:00:00Z",
  "last_used_at": null
}

Warning: The key field is shown only once. Copy it immediately and store it securely. It cannot be retrieved after this response.

Authenticating with an API Key

bash

# curl
curl -X POST https://api.zkesg.com/api/v1/proofs \
  -H "Authorization: Bearer $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "carbon_emissions",
    "inputs": { "scope1": 1240.5, "scope2": 870.2, "threshold": 2500 }
  }'

Listing Keys

http

GET /api/v1/keys HTTP/1.1
Host: api.zkesg.com
Authorization: Bearer <your-session-token-or-api-key>

json

{
  "keys": [
    {
      "id": "key_01HX4KQZR9BNT5E2FPMCDVWJ3",
      "name": "ci-pipeline-prod",
      "description": "Used by GitHub Actions for nightly proof batch",
      "created_at": "2026-03-16T12:00:00Z",
      "last_used_at": "2026-03-16T14:23:11Z"
    }
  ],
  "total": 1,
  "limit": 10
}

Revoking a Key

bash

curl -X DELETE "https://api.zkesg.com/api/v1/keys/key_01HX4KQZR9BNT5E2FPMCDVWJ3" \
  -H "Authorization: Bearer $MINERVA_API_KEY"

Revocation is permanent. Any subsequent requests using the revoked key return 401 Unauthorized.

Rate Limits

Limit	Value
API keys per account	10
Proof requests per minute (per key)	60
Proof requests per day (per account)	5,000
Batch proof size	100 proofs per request
Concurrent proof jobs	10

Error Reference

Status	Code	Meaning
401	invalid_api_key	Key is missing, malformed, or revoked
403	insufficient_scope	Key does not have permission for this operation
404	key_not_found	Key ID does not exist in your account
409	key_limit_reached	Account already has 10 active keys
429	rate_limit_exceeded	Too many requests — back off and retry

← Back to Documentation