API Keys
Create, list, and revoke API keys for programmatic access to Savannah Cloud.
API keys allow services to push jobs and access platform resources without managing a user session.
The raw key value is returned only once at creation time. Store it securely and do not print it in logs.
List API keys
GET /api-keys
Authorization: Bearer <token>Response 200
[
{
"id": "key_abc123",
"name": "CI pipeline",
"created_at": "2026-05-01T09:00:00Z",
"last_used_at": "2026-05-24T10:00:00Z"
}
]Create API key
POST /api-keys
Authorization: Bearer <token>
Content-Type: application/jsonRequest body
{
"name": "CI pipeline"
}Response 201
{
"key": {
"id": "key_abc123",
"name": "CI pipeline",
"created_at": "2026-05-24T10:00:00Z"
},
"raw_key": "sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}Delete / revoke API key
DELETE /api-keys/{id}
Authorization: Bearer <token>Response 204 No Content
The key is invalidated immediately.
Use an API key
Pass the raw key in either of these forms:
X-API-Key: sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxor
Authorization: Bearer sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBoth forms are equivalent; the X-API-Key header is preferred for machine clients.
Quick reference
# List keys
curl http://localhost:8080/api-keys \
-H "Authorization: Bearer YOUR_JWT"
# Create a key
curl -X POST http://localhost:8080/api-keys \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{"name":"production"}'
# Revoke a key
curl -X DELETE http://localhost:8080/api-keys/key_abc123 \
-H "Authorization: Bearer YOUR_JWT"