Skip to content

API Keys

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

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)
  1. Navigate to Admin > API Keys
  2. Click Create API Key
  3. Enter a name and description
  4. Select scopes
  5. Optionally set an expiration date
  6. Click Create
  7. Copy the key immediately (it won’t be shown again)
Terminal window
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"
}'

Include the key in the Authorization header:

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

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

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; create, update and delete approval policies
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 admin settings
admin:write Update settings and manage users
internal:service Service-to-service communication

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.

Repository endpoints accept either family: a key with repositories:read or catalog:read can read repositories, and syncing or refreshing one takes repositories:write or catalog:write. Scopes never cross families otherwise, so repositories:admin doesn’t grant catalog:read.

The *:admin scopes are only available on keys created in Admin. Personal access tokens can’t hold them, so anything that needs an admin scope, like managing approval policies with forge:admin, needs an admin-managed key.

Terminal window
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.

Terminal window
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.

An admin can make keys stop working once nobody has used them for a while. Turn it on under Admin > Policies > API key expiry. It is off until you turn it on, and upgrading never turns it on for you.

While it is on:

  • A key or personal access token stops working 90 days after its last request. A key that has never been used counts from the day it was created.
  • A key that also has its own expiry date stops working on whichever comes first.
  • Any request that authenticates counts as use, including the REST API and MCP.
  • A client still using an expired key gets a 401 with the error code API_KEY_IDLE_EXPIRED, so a script can tell this apart from a key that is simply wrong. The message reads “This API key stopped working after 90 days without use. Create a new one.”

The API Keys page and your personal access tokens show when each key lapses, and flag the ones that already have. Nothing is deleted: an expired key is still listed, and still yours to revoke.

Turn the setting back off and those keys start working again.

  • Maximum 25 active keys per user
  • An expiry date is optional. Without one a key lasts until it is revoked, unless API key expiry is on
  • All key usage is logged with last_used_at timestamp
  • 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)
Use Case Recommended Scopes
CI/CD entity updates catalog:read, catalog:write
Terraform provider catalog:admin, k8s-agents:admin, forge:admin
Read-only dashboard catalog:read, operations:read
K8s agent k8s-agents:write, operations:write
Monitoring integration catalog:read, operations:read