API documentation

Authentication

Every request to the Stonewake API carries an API key as a Bearer token in the Authorization header:

bash
curl https://api.stonewake.ai/v1/portfolio \
  -H "Authorization: Bearer swk_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

The key above is a placeholder. Real keys are the prefix swk_live_ followed by 40 random characters.

How keys work

  • Keys are created by a workspace admin in the dashboard. See Keys and access management.
  • The full key is shown exactly once, at creation. It is stored as a one-way hash and cannot be retrieved again. If a key is lost, create a new one.
  • Keys are scoped to your workspace. A key can only read data that belongs to the workspace it was created in.
  • Keys are read-only. A key cannot change anything in your workspace, and it cannot manage keys, including itself.
  • Keys are revocable instantly. Revocation takes effect on the key's next request.
  • Keys can carry an optional expiry, set at creation.

The 401 posture

A /v1 request whose credential is missing or not accepted receives one and the same response, whatever the reason:

json
{
  "error": {
    "code": "unauthenticated",
    "message": "Missing or invalid credentials."
  }
}

A missing header, a malformed key, a wrong key, a revoked key, an expired key, and a key from a workspace whose API access has lapsed are indistinguishable in the response. The API does not reveal why a credential was refused, or whether it ever existed. If a previously working key starts receiving 401, check its status in the dashboard.

Handling rules

Treat API keys like passwords.

  • Never put a key in a URL or query string. It travels in the Authorization header only.
  • Never ship a key in client-side code or anything a browser downloads. Calls belong on your server side.
  • Keep keys out of source control and logs. Store them in a secrets manager or an environment variable.
  • Rotate on suspicion. If a key may have been exposed, create a replacement and revoke the old key immediately.