Programmatic API + account API keys

This guide covers the API-driven workflow added in Crucible 0.9.0. For the full endpoint reference see the API reference; for a machine-readable spec see /api/openapi.json (OpenAPI 3.1).

The two key types

Older agents may still have col_* collector keys. Both formats authenticate against /api/v1/ingest; you can rotate at your own pace.

Quickstart: provision 50 servers in two minutes

1. Create an account API key

Account API keys are created via the API itself (no settings UI in v1.0; UI lands in v1.x). The flow is two calls:

# 1. Re-authenticate (opens a 5-minute step-up window).
curl -sS -X POST https://app.glassmkr.com/api/v1/account/verify-password \
  -b session.cookie \
  -H "Content-Type: application/json" \
  -d '{"password":"your-dashboard-password"}'

# 2. Create the key (returned in plaintext exactly once; save it).
curl -sS -X POST https://app.glassmkr.com/api/v1/account/keys \
  -b session.cookie \
  -H "Content-Type: application/json" \
  -d '{"name":"ansible-prod","scopes":["servers:manage"]}'

Use a logged-in browser session (cookie jar). Account-key creation cannot use another account key (no API-key-creating-API-key in v1).

2. Create the servers via curl

API_KEY="gmk_acct_live_..."
INGEST_URL="https://app.glassmkr.com/api/v1/ingest"

for i in $(seq 1 50); do
  RESPONSE=$(curl -sS -X POST https://app.glassmkr.com/api/v1/servers \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: bootstrap-$(date +%s)-$i" \
    -d '{"name":"web-'$i'","hostname":"web-'$i'.prod.example.com","tags":["prod","web"]}')

  COLLECTOR_KEY=$(echo "$RESPONSE" | jq -r '.server.api_key')
  echo "web-$i  →  $COLLECTOR_KEY"
done

3. Provision the agent on each host

curl -sf https://glassmkr.com/install.sh | sudo GLASSMKR_API_KEY=$COLLECTOR_KEY bash

Rate limits

Three default tiers (per-IP, per-key, per-account) plus per-endpoint sub-limits for the high-risk operations:

On 429, the response body includes tier and retry_after_seconds; the Retry-After header is set.

Idempotency

POST /api/v1/servers accepts an Idempotency-Key header (Stripe-style). Retries within 24h with the same key return the cached response (status + body). Use one for every retried server-creation operation in your automation.

Step-up authentication

API key creation and rotation require recent password re-verification. POST your current password to /api/v1/account/verify-password (session auth, not bearer-token) to stamp last_password_verified_at. After that, sensitive operations succeed for 5 minutes.

This protects against session-stealing attacks: an attacker with a leaked cookie cannot mint a long-lived API key without also knowing the password.

Audit log

Every API call writes one row to the audit log. Read it via GET /api/v1/account/audit:

• Paginated by ts cursor (?limit=50&cursor=...)
• Filterable by key_id, resource_type, resource_id, action, result
• Plan-based retention: 365 days for Pro, 30 days for Free
• Append-only: we cannot edit history server-side

Securing your keys

• Store in your secret manager (1Password, Vault, AWS Secrets Manager, Doppler). Never in .env committed to git.
• Use a separate key per integration (Ansible, CI, Terraform). Revoking one doesn't disrupt the others.
• Set an expires_at on short-lived CI keys.
• If a key leaks: revoke immediately at DELETE /api/v1/account/keys/{id} or via the dashboard.
• GitHub secret-scanning partner registration for gmk_acct_live_ + gmk_cru_live_ prefixes is queued; once active, accidentally-committed keys auto-revoke.

Errors

Standard envelope:

{
  "error": "machine_readable_code",
  "message": "Human-readable explanation",
  "request_id": "req_abc123",
  "documentation_url": "https://glassmkr.com/docs/api/errors/{code}"
}

Use request_id when contacting support; we correlate it against the audit log + application logs.