Savannah Cloud

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/json

Request 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

or

Authorization: Bearer sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Both 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"

On this page