KMS - Usage Guide

AI Context Reference

Copy and paste this into any AI chat so it knows how to use the KMS API.

<kms-api-reference>
  <name>Key Management Service (KMS)</name>
  <description>
    Centralized API key vault. Stores AI provider keys encrypted (AES-256-GCM)
    and serves them to authorized services via service tokens.
    Use this instead of hardcoding API keys.
  </description>
  <base-url>https://admin.zedz.co.za</base-url>

  <authentication>
    <method name="service-token" use="programmatic access from apps">
      <header>X-Service-Token: YOUR_TOKEN</header>
      <note>Generated via admin dashboard. Shown once at creation - save immediately.</note>
    </method>
    <method name="admin-jwt" use="managing keys and tokens">
      <header>Authorization: Bearer YOUR_JWT</header>
      <obtain>POST /api/auth/login with {"email":"...","password":"..."}</obtain>
      <expires>24 hours</expires>
    </method>
  </authentication>

  <endpoints>
    <endpoint method="GET" path="/api/v1/keys/{provider}" auth="service-token">
      <description>Fetch a decrypted API key by provider</description>
      <providers>openai, xai, groq</providers>
      <response>{"provider":"openai","key_name":"main-key","api_key":"sk-..."}</response>
    </endpoint>

    <endpoint method="GET" path="/health" auth="none">
      <description>Health check</description>
      <response>{"status":"healthy","database":"connected"}</response>
    </endpoint>

    <endpoint method="POST" path="/api/auth/login" auth="none">
      <description>Login, returns JWT token</description>
      <body>{"email":"...","password":"..."}</body>
      <response>{"token":"eyJ..."}</response>
    </endpoint>

    <endpoint method="GET" path="/api/keys" auth="admin-jwt">
      <description>List all stored API keys (values not included)</description>
    </endpoint>

    <endpoint method="POST" path="/api/keys" auth="admin-jwt">
      <description>Store a new API key (encrypted at rest)</description>
      <body>{"provider":"openai|xai|groq","key_name":"...","api_key":"sk-..."}</body>
    </endpoint>

    <endpoint method="PATCH" path="/api/keys/{id}" auth="admin-jwt">
      <description>Activate or deactivate a key</description>
      <body>{"is_active": true|false}</body>
    </endpoint>

    <endpoint method="DELETE" path="/api/keys/{id}" auth="admin-jwt">
      <description>Delete a stored API key</description>
    </endpoint>

    <endpoint method="GET" path="/api/service-tokens" auth="admin-jwt">
      <description>List all service tokens</description>
    </endpoint>

    <endpoint method="POST" path="/api/service-tokens" auth="admin-jwt">
      <description>Generate a new service token</description>
      <body>{"service_name":"my-app"}</body>
      <response>{"token":"abc123..."}</response>
      <note>Token shown ONCE. Cannot be retrieved later.</note>
    </endpoint>

    <endpoint method="PATCH" path="/api/service-tokens/{id}" auth="admin-jwt">
      <description>Activate or deactivate a service token</description>
      <body>{"is_active": true|false}</body>
    </endpoint>

    <endpoint method="DELETE" path="/api/service-tokens/{id}" auth="admin-jwt">
      <description>Delete a service token</description>
    </endpoint>
  </endpoints>

  <usage-example lang="typescript">
const res = await fetch("https://admin.zedz.co.za/api/v1/keys/openai", {
  headers: { "X-Service-Token": process.env.KMS_SERVICE_TOKEN! },
});
const { api_key } = await res.json();
  </usage-example>

  <usage-example lang="curl">
curl -s https://admin.zedz.co.za/api/v1/keys/openai   -H "X-Service-Token: YOUR_TOKEN"
  </usage-example>

  <environment-variable>
    <name>KMS_SERVICE_TOKEN</name>
    <description>Service token for authenticating with KMS</description>
  </environment-variable>
</kms-api-reference>

What is KMS?

KMS (Key Management Service) is a centralized, secure vault for your AI provider API keys. Instead of hardcoding secrets like sk-... into your apps, you store them here encrypted and fetch them on demand.

API keys are encrypted at rest with AES-256-GCM
Access is controlled via service tokens (for apps) or JWT (for admin)
Supports OpenAI, xAI (Grok), and Groq providers
All access is logged for audit

How It Works

1

Admin stores API keys

Log into the admin dashboard, go to the API Keys tab, and add your provider keys. They are encrypted before being stored in the database.

2

Admin generates a service token

Go to the Service Tokens tab and generate a token for your app. Copy and save it immediately — it cannot be retrieved again (only the hash is stored).

3

Your app fetches keys via API

Your app sends a request to KMS with the service token and gets back the decrypted API key for the requested provider.

Quick Start

Fetch an API Key (cURL)

curl -s https://admin.zedz.co.za/api/v1/keys/openai \
  -H "X-Service-Token: YOUR_SERVICE_TOKEN"

Replace openai with xai or groq for other providers.

Response

{
  "provider": "openai",
  "key_name": "main-key",
  "api_key": "sk-proj-..."
}

Integration Examples

TypeScript / Bun

const KMS_URL = "https://admin.zedz.co.za";
const SERVICE_TOKEN = process.env.KMS_SERVICE_TOKEN;

async function getApiKey(provider: "openai" | "xai" | "groq"): Promise<string> {
  const res = await fetch(\`\${KMS_URL}/api/v1/keys/\${provider}\`, {
    headers: { "X-Service-Token": SERVICE_TOKEN! },
  });

  if (!res.ok) {
    throw new Error(\`KMS error: \${res.status}\`);
  }

  const data = await res.json();
  return data.api_key;
}

// Usage
const openaiKey = await getApiKey("openai");

Python

import os
import requests

KMS_URL = "https://admin.zedz.co.za"
SERVICE_TOKEN = os.environ["KMS_SERVICE_TOKEN"]

def get_api_key(provider: str) -> str:
    resp = requests.get(
        f"{KMS_URL}/api/v1/keys/{provider}",
        headers={"X-Service-Token": SERVICE_TOKEN},
    )
    resp.raise_for_status()
    return resp.json()["api_key"]

# Usage
openai_key = get_api_key("openai")

Docker / Environment Variable

Set the service token as an environment variable in your docker-compose.yml or .env file:

# .env
KMS_SERVICE_TOKEN=your-service-token-here

# docker-compose.yml
services:
  my-app:
    environment:
      - KMS_SERVICE_TOKEN=${KMS_SERVICE_TOKEN}

API Reference

Method	Endpoint	Auth	Description
GET	/api/v1/keys/:provider	Service Token	Fetch an API key by provider
GET	/health	None	Health check
POST	/api/auth/login	None	Login (returns JWT)
GET	/api/keys	Admin JWT	List all API keys
POST	/api/keys	Admin JWT	Add a new API key
GET	/api/service-tokens	Admin JWT	List service tokens
POST	/api/service-tokens	Admin JWT	Generate a new service token

Authentication Headers

For apps/services (Service Token)

X-Service-Token: your-service-token-here

For admin operations (JWT)

Authorization: Bearer your-jwt-token-here

Supported Providers

OpenAI

openai

GPT-4, DALL-E, etc.

xAI

xai

Grok models

Groq

groq

Fast inference

Troubleshooting

401 Unauthorized

Your service token is missing, invalid, or has been deactivated. Check the X-Service-Token header and verify the token is active in the admin dashboard.

404 Not Found on /api/v1/keys/:provider

No active key exists for that provider. Add one via the admin dashboard first.

Service token was not saved

Service tokens are only shown once when created. If you lost it, deactivate/delete the old token and generate a new one from the admin dashboard.