Authentication & Errors

API calls accept bearer tokens. Tokens use tk_ plus 64 lowercase hex characters, are sha256-hashed at rest, have no expiry, and return 401 when missing or invalid.

Bearer Tokens#

Send the token in the Authorization header on every request. Plaintext tokens are returned only when created by POST /api/tokens. Store the value immediately; later reads return metadata only.

header

Authorization: Bearer tk_<64 lowercase hex chars>

Base URL#

Use your deployed instance URL, usually the same value configured as NEXTAUTH_URL. This page does not hardcode a host because self-hosted Timekeeper instances vary.

Errors#

Code	Meaning
`400`	Invalid JSON, invalid query params, invalid date, failed Zod validation, or impossible time range.
`401`	Missing or invalid token.
`403`	Forbidden resource access. Current owned-resource handlers generally return 404 to avoid disclosure.
`404`	Open session, entity, audit record, file, comment, token, or owned resource not found.
`409`	Already checked in.
`422`	Session too short to save, under one minute.

Revoked tokens stop authenticating immediately and future requests with that value return 401.