Authentication

Key format, the one moment a secret is visible, expiry options, and rotation.

Every request carries a bearer token in the Authorization header. A request with no header, or a header that does not begin with Bearer , is rejected as 401 before any lookup happens — the same response an expired key gets, and deliberately so.

A minimal authenticated request

curl https://hawiagents.com/api/v1/auth \
  -H "Authorization: Bearer hawi_sk_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXX"

What /auth returns

Call it first when something is not working. It answers the question “is this key valid, and what is it allowed to do” without touching any data.

{
  "authenticated": true,
  "keyId": "…",
  "workspaceId": "…",
  "scopes": ["files:read", "workspace:read"],
  "expiresAt": "…",
  "totalRequests": 1284
}

keyId: The key's identifier. Safe to log; it is not the secret.
workspaceId: The one workspace this key can read. Any other id returns 404.
scopes: Sorted, de-duplicated, and exactly what was granted at issue.
expiresAt: When the key stops working. There is no non-expiring key.
totalRequests: Lifetime request count for this key. Useful for spotting a key that is being used somewhere you forgot about.

Key format

Keys are issued as hawi_sk_<public id>_<secret>. The public id identifies the key so it can be looked up, rate-limited and revoked; the secret is the part that proves you hold it.

Expiry

A key is issued with an expiry chosen from 7, 30, 90, 365 days. Ninety is the default and is the right answer for most integrations.

Expiry	Suits
7 days	A one-off script, a migration, something you are debugging.
30 days	A contractor, a trial integration, anything you expect to revisit.
90 days	The default. A running integration with an owner who will notice the rotation.
365 days	A long-lived internal service. Set a calendar reminder at eleven months, because nothing else will.

Rotation

Rotating issues a new secret against the same key with a fresh expiry. Rotate on a schedule, when somebody with access leaves, and immediately if a key has appeared anywhere it should not — a log, a screenshot, a repository, a support ticket.