Quick Start

Create and verify your first Solenoid Key API key in under 5 minutes.

All endpoints require a Bearer token. See Authentication.

Create an API key

curl -X POST https://api.solenoid.systems/v1/keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "myapp_live",
    "name": "Production API Key",
    "scopes": ["orders:read", "orders:write"],
    "environment": "production",
    "metadata": { "team": "api" }
  }'

Response:

{
  "key_id": "550e8400-e29b-41d4-a716-446655440000",
  "secret": "myapp_live_A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0_12ab34cd",
  "name": "Production API Key",
  "prefix": "myapp_live",
  "scopes": ["orders:read", "orders:write"],
  "environment": "production",
  "created_at": "2026-02-05T12:00:00Z"
}

Save the secret immediately. It is never shown again.

Verify keys

HTTP

curl -X POST https://api.solenoid.systems/v1/keys/verify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "myapp_live_A1B2C3...T0_12ab34cd"
  }'

IP and user agent are captured automatically from request headers (CF-Connecting-IP, User-Agent).

Valid response:

{
  "valid": true,
  "key_id": "550e8400-e29b-41d4-a716-446655440000",
  "scopes": ["orders:read", "orders:write"]
}

Invalid response:

{ "valid": false, "error": "invalid_key" }

RPC binding (Cloudflare Workers)

const result = await env.KEY.verify(apiKey, {
  ip: request.headers.get('CF-Connecting-IP'),
  userAgent: request.headers.get('User-Agent')
})

if (!result.valid) {
  return new Response(`Invalid key: ${result.error}`, { status: 401 })
}

if (!result.scopes.includes('orders:read')) {
  return new Response('Insufficient scope', { status: 403 })
}

Rotate keys

Both old and new keys work during the grace period.

curl -X POST https://api.solenoid.systems/v1/keys/550e8400-e29b-41d4-a716-446655440000/rotate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "grace_hours": 24 }'

Deploy the new key before the grace period ends. The old key stops working at old_expires_at.

Revoke keys

Revocation is immediate. Use when a key is compromised.

curl -X DELETE https://api.solenoid.systems/v1/keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Revoked keys fail verification instantly. Cache is cleared automatically.

Next steps