Core concepts
Authentication
Key and secret headers, the bearer fallback, and why every failure looks the same.
Two accepted schemes, resolved identically.
Preferred — key/secret headers:
X-Staylah-Key: slk_live_9f2c1ab34d5e6f7089ab12cd
X-Staylah-Secret: <64 hex chars>
Fallback — bearer, for HTTP clients that only expose a token field. The separator is a dot; the key id contains none:
Authorization: Bearer slk_live_9f2c1ab34d5e6f7089ab12cd.<secret>
Pick one scheme; do not send both. The header pair wins, but only when
both X-Staylah-Key and X-Staylah-Secret are present. Send
X-Staylah-Key alone alongside a valid bearer token and the bearer is used;
send X-Staylah-Key alone with no bearer and the request is rejected as though
no credentials were sent at all. A half-populated header pair is the usual cause
of a 401 that a partner is certain should have worked.
Optional / other headers#
| Header | Purpose |
|---|---|
X-Staylah-Request-Id | Your own correlation id. Echoed back in request_id (truncated to 64 chars). Send one — it joins your logs to ours in a support thread. |
X-Staylah-Timestamp | Unix seconds. Required only when your key has signing enabled. |
X-Staylah-Signature | sha256=<hex>. Required only when your key has signing enabled. |
Secrets#
The secret is shown exactly once, at issue or rotation. Nothing at Staylah can retrieve it afterwards. If you lose it, the only remedy is a rotation.
Rotation issues a new key and gives the old one a 24-hour overlap window by
default, so you can deploy the new secret without downtime. For a key you
believe is compromised, ask for overlap_hours: 0 and the old key dies
immediately.
Every auth failure looks the same#
Unknown key, wrong secret, revoked, expired, deactivated partner, blocked IP, wrong environment, bad signature, replayed signature — all return the identical body:
{
"success": false,
"error": { "code": "unauthorized", "message": "Invalid or missing API credentials." },
"request_id": "0f1e…"
}
The specific reason is recorded in our access log only; returning it would hand
an attacker a key-enumeration oracle. If you are stuck, call /whoami with a
key you know works, or quote a request_id to Staylah support and we will read
the real reason out of the log.