API Keys
API keys provide programmatic access to the Shoehorn API for automation, CI/CD pipelines, and service-to-service communication.
Key Format
Section titled “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
Section titled “Creating API Keys”Via the UI
Section titled “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
Section titled “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
Section titled “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
Section titled “Scopes”Scopes define what an API key can access. Use the minimum scopes needed.
Available Scopes
Section titled “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; 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 |
Scope Hierarchy
Section titled “Scope Hierarchy”Higher scopes include all permissions of lower scopes:
resource:admin -> resource:write -> resource:readFor 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.
Key Management
Section titled “Key Management”Listing Keys
Section titled “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
Section titled “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.
Expiry for unused keys
Section titled “Expiry for unused keys”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.
Limits
Section titled “Limits”- 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_attimestamp
Security
Section titled “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_atis updated asynchronously (does not block requests)
Common Use Cases
Section titled “Common Use Cases”| 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 |