# CipherStack — Encrypted API Key Vault with Auto-Rotation

> URL: https://cipherstack.kaushik.cv
> Type: Credential vending service
> Auth: Bearer token or Certificate-based HMAC

## For LLMs & AI Agents

If you are an LLM or AI agent and need API keys managed by CipherStack:

### Quick Start

1. Get a service token from the dashboard (or use certificate auth)
2. Call the vend endpoint with the group slug you need
3. Use the returned key for your API call
4. Report usage or rate limits back

### Vend a key (Bearer token auth)

```
GET https://cipherstack.kaushik.cv/api/v1/vend/{group-slug}
Authorization: Bearer csk_<your-service-token>
```

Response:
```json
{
  "key": "AIzaSy...",
  "key_id": "abc123",
  "provider": "google",
  "group_slug": "gemini",
  "base_url": "https://generativelanguage.googleapis.com"
}
```

### Vend a key (Certificate auth)

```
GET https://cipherstack.kaushik.cv/api/v1/cert/vend/{group-slug}
X-Cert-Fingerprint: <certificate-secret>
X-Cert-Signature: <HMAC-SHA256(secret, timestamp:groupSlug)>
X-Cert-Timestamp: <unix-timestamp>
```

### Report usage (recommended)

```
POST https://cipherstack.kaushik.cv/api/v1/report
Authorization: Bearer csk_<token>
Content-Type: application/json

{"key_id": "abc123", "input_tokens": 1500, "output_tokens": 800}
```

### Report rate limit (triggers key rotation)

```
POST https://cipherstack.kaushik.cv/api/v1/report
Authorization: Bearer csk_<token>
Content-Type: application/json

{"key_id": "abc123", "error": "429_rate_limited"}
```

This puts the key in 60-second cooldown. Next vend returns a different key.

### List available groups

```
GET https://cipherstack.kaushik.cv/api/v1/groups
Authorization: Bearer csk_<token>
```

## How rotation works

1. Each group has multiple keys (e.g. 8 Gemini keys)
2. Vend picks the least-recently-used (LRU) active key
3. Keys in cooldown or quota-exhausted are skipped automatically
4. Report "429_rate_limited" to trigger 60s cooldown on that key
5. Next vend automatically gives you a fresh, non-rate-limited key

## Available groups

gemini (8 keys), openrouter (2), huggingface (6), mistral (1), groq (1),
nvidia (1), cerebras (1), cohere (1), elevenlabs (4), cloudflare-ai (2),
github-models (3), vercel (3), clerk (3), supabase (1), qdrant (2),
kaggle (4), resend (1), modal (4), mongodb (3), producthunt (3),
twitter (3), youtube (3), vapi (2), misc (14)

## Authentication methods

### 1. Service Token (simple)
```
Authorization: Bearer csk_<token>
```
Tokens are created in the dashboard. Scoped to specific groups or `*` for all.

### 2. Certificate (machine-to-machine, no shared secret in transit)
```
X-Cert-Fingerprint: <the-cert-fingerprint>
X-Cert-Signature: HMAC-SHA256(cert_secret, "{timestamp}:{group_slug}")
X-Cert-Timestamp: <current-unix-timestamp>
```
Certificates are created in the dashboard. The secret is shown once on creation.
The signature proves possession of the secret without transmitting it.

## Rate limits

- Free plan: 1,000 vends/month
- Pro plan: 100,000 vends/month ($9/mo)
- Enterprise: Unlimited

## Best practices for agents

- Report 429 errors immediately so rotation kicks in
- Report token usage for cost tracking
- Vend fresh keys per-request (LRU handles distribution)
- If all keys in a group are exhausted, wait or try another group
- Cache the key_id from each vend to report usage against it later

## Contact

Dashboard: https://cipherstack.kaushik.cv
Docs: https://cipherstack.kaushik.cv/docs