API Keys

API keys provide programmatic access to the Shoehorn API for automation, CI/CD pipelines, and service-to-service communication.

Key Format

API keys follow the format: shp_svc_<72-character-random-string>

The shp_svc_ prefix identifies it as a Shoehorn service key
Keys are shown only once at creation time
Keys are stored as bcrypt hashes (cost 12)

Creating API Keys

Via the UI

Navigate to Admin > API Keys
Click Create API Key
Enter a name and description
Select scopes
Optionally set an expiration date
Click Create
Copy the key immediately (it won’t be shown again)

Via the API

curl -X POST https://shoehorn.example.com/api/v1/admin/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "description": "Used by GitHub Actions",
    "scopes": ["catalog:read", "catalog:write"],
    "expires_at": "2026-12-31T00:00:00Z"
  }'

Using API Keys

Include the key in the Authorization header:

curl https://shoehorn.example.com/api/v1/entities \
  -H "Authorization: Bearer shp_svc_xxxxxxxxxxxx"

Scopes

Scopes define what an API key can access. Use the minimum scopes needed.

Available Scopes

Scope	Description
`catalog:read`	Read entities, search, stats
`catalog:write`	Create and update entities
`catalog:admin`	Delete entities
`forge:read`	Read molds and workflow runs
`forge:write`	Create and execute workflows
`forge:admin`	Delete molds and runs
`repositories:read`	Read repository data
`repositories:write`	Update repository data
`repositories:admin`	Full repository management
`k8s-agents:read`	Read cluster and agent data
`k8s-agents:create`	Register new clusters
`k8s-agents:update`	Update agent configuration
`k8s-agents:delete`	Remove clusters
`k8s-agents:write`	Create, update, delete agents
`k8s-agents:admin`	Full agent management
`operations:read`	Read workloads and GitOps data
`operations:write`	Update operations resources
`operations:admin`	Full operations management
`admin:read`	Read settings and audit logs
`admin:write`	Update settings and manage users
`internal:service`	Service-to-service communication

Scope Hierarchy

Higher scopes include all permissions of lower scopes:

resource:admin  ->  resource:write  ->  resource:read

For example, catalog:admin grants catalog:write and catalog:read automatically.

Key Management

Listing Keys

curl https://shoehorn.example.com/api/v1/admin/api-keys \
  -H "Authorization: Bearer <token>"

Keys are listed with their prefix (first 12 characters) for identification, not the full key.

Revoking a Key

curl -X DELETE https://shoehorn.example.com/api/v1/admin/api-keys/<key-id> \
  -H "Authorization: Bearer <token>"

Revoked keys are immediately invalid. The revocation is recorded with a timestamp.

Limits

Maximum 25 active keys per user
Key expiration is optional (keys can be permanent)
All key usage is logged with last_used_at timestamp

Security

Keys are hashed with bcrypt (cost 12) before storage
Key lookups use a prefix index for performance
Failed authentication returns a generic error (prevents enumeration)
Successful key validations are cached for 5 minutes (SHA256 of key)
last_used_at is updated asynchronously (does not block requests)

Common Use Cases

Use Case	Recommended Scopes
CI/CD entity updates	`catalog:read`, `catalog:write`
Terraform provider	`catalog:admin`, `k8s-agents:admin`
Read-only dashboard	`catalog:read`, `operations:read`
K8s agent	`k8s-agents:write`, `operations:write`
Monitoring integration	`catalog:read`, `operations:read`