REST API
Keysmith REST API endpoints for key management.
When mounted via the Forge extension, Keysmith exposes a complete REST API for managing API keys, policies, scopes, usage, and rotations.
Keys
Create API key
POST /v1/keysRequest body:
{
"name": "Production Key",
"prefix": "sk",
"environment": "live",
"scopes": ["read:users", "write:users"],
"policy_id": "kpol_01h2xce...",
"expires_at": "2025-12-31T23:59:59Z"
}Response (201):
{
"raw_key": "sk_live_a3f8b2c9e1d4...",
"key": {
"id": "akey_01h2xce...",
"name": "Production Key",
"prefix": "sk",
"environment": "live",
"state": "active",
"scopes": ["read:users", "write:users"],
"created_at": "2024-01-15T10:30:00Z"
}
}List API keys
GET /v1/keys?limit=50&offset=0&state=active&environment=liveGet API key
GET /v1/keys/:keyIdDelete API key
DELETE /v1/keys/:keyIdValidate API key
POST /v1/keys/validateRequest body:
{
"raw_key": "sk_live_a3f8b2c9e1d4..."
}Response (200):
{
"valid": true,
"key": {
"id": "akey_01h2xce...",
"name": "Production Key",
"state": "active",
"tenant_id": "tenant-1"
},
"scopes": ["read:users", "write:users"]
}Rotate API key
POST /v1/keys/:keyId/rotateRequest body:
{
"reason": "scheduled",
"grace_period": "24h"
}Revoke API key
POST /v1/keys/:keyId/revokeRequest body:
{
"reason": "compromised"
}Suspend API key
POST /v1/keys/:keyId/suspendReactivate API key
POST /v1/keys/:keyId/reactivatePolicies
Create policy
POST /v1/policiesRequest body:
{
"name": "Standard API",
"rate_limit": 1000,
"rate_window": "1m",
"allowed_ips": ["10.0.0.0/8"],
"allowed_origins": ["https://app.example.com"],
"max_key_age": "2160h"
}List policies
GET /v1/policies?limit=50&offset=0Get policy
GET /v1/policies/:policyIdUpdate policy
PUT /v1/policies/:policyIdDelete policy
DELETE /v1/policies/:policyIdScopes
Create scope
POST /v1/scopesRequest body:
{
"name": "read:users",
"description": "Read user profiles"
}List scopes
GET /v1/scopes?limit=100&offset=0Delete scope
DELETE /v1/scopes/:scopeIdAssign scopes to key
POST /v1/keys/:keyId/scopesRequest body:
{
"scopes": ["read:billing", "write:billing"]
}Remove scopes from key
DELETE /v1/keys/:keyId/scopesRequest body:
{
"scopes": ["write:billing"]
}Usage
Get key usage
GET /v1/keys/:keyId/usage?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&limit=100Get usage aggregation
GET /v1/keys/:keyId/usage/aggregate?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&granularity=dailyList tenant usage
GET /v1/usage?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&limit=1000Rotations
List key rotations
GET /v1/keys/:keyId/rotations?limit=10