Direct kAuth Authentication

If you already hold a Knowify session token, you can authenticate against the API directly — without the OAuth flow.

Authorization: kauth <kauth-token>

That's the entire auth header. Same idea as the legacy Authorization: Key <id> <secret> pattern, but for kAuth tokens.

When to use it

Situation	Recommended path
Server-side scripts or jobs you control	Direct kAuth
Third-party applications consenting users authorize	OAuth 2.0
Long-running integration where you want automatic token refresh	OAuth 2.0 with refresh tokens
Quick one-off integration test	Direct kAuth
Anything that holds the kauth on a user's behalf (you're the consumer)	Direct kAuth

The two paths reach the same endpoints. Pick based on lifecycle ergonomics, not capability.

What you get

A direct-kAuth request is granted the admin meta-scope — full read + write access across every resource. kAuth tokens are issued by Knowify to authenticated users who already hold full backend permissions; re-litigating scope at this layer would be theater.

If you need narrower scopes (e.g. to give a delegated integration only invoices:read), use OAuth — that's what OAuth scopes are for.

How validation works

1. Your request arrives with Authorization: kauth <token>.
2. The API validates the token against the Knowify backend (a cheap probe call).
3. On success: the identity is briefly cached in Redis (~60s) and your request proceeds.
4. On failure: 401 — the token has been revoked, expired, or never existed.

Cache TTL is short. A revoked token starts failing within roughly a minute.

Token lifecycle

You manage the token yourself. The API doesn't refresh kAuth tokens for direct-kauth requests — that's the consumer's responsibility.

• kAuth tokens are valid for 10 days from issuance.
• Refresh via POST {backend}/SaaS/RefreshToken with the current token as a kauth header. The response includes a fresh token in the kauth response header.
• If you'd prefer managed refresh, use OAuth — its refresh tokens have the same 10-day window and rotate on use.

Heads up

There's no "your token expires in N hours" hint on the response from this endpoint yet. If you're holding a kauth for any length of time, schedule a refresh ahead of the 10-day mark — don't wait for a 401.

Example

curl https://developer.knowify.com/api/v2/projects \
  -H "Authorization: kauth ${KNOWIFY_KAUTH_TOKEN}"

const projects = await fetch('https://developer.knowify.com/api/v2/projects', {
  headers: { Authorization: `kauth ${kauthToken}` },
}).then((r) => r.json());

Identical body, identical response shape, identical error format — only the auth header differs from the OAuth path.

Differences from OAuth

Aspect	OAuth 2.0	Direct kAuth
Auth header	Authorization: Bearer <access-token>	Authorization: kauth <kauth-token>
Setup	Client registration, consent flow, token exchange	Just have a kauth token
Token lifetime	5 days (access), 10 days (refresh)	10 days
Refresh	Built-in via refresh token	Caller's responsibility (SaaS/RefreshToken)
Scope	Granted by the consenting user	Always admin
Audit	Identifies the OAuth client + user	Identifies the user only
Use case	Third-party apps, scoped integrations	First-party scripts, internal automation