Authentication

The Hoursmith API authenticates every request with a Bearer token in the Authorization header. There are no cookies or sessions.

The Authorization header

Send your token as a Bearer credential on every request:

GET /api/v1/clients HTTP/1.1
Host: hoursmith.app
Authorization: Bearer hsk_live_4f8a2c1bdedf_9X3kQp7vT2nM5wRzL8sJyB6FhA1uC0gE
Accept: application/json

Token format

Hoursmith tokens have a recognizable shape so they're easy to spot (and revoke) if they ever leak:

hsk_<env>_<prefix>_<secret>

• hsk — a constant brand marker, greppable in logs and code.
• <env> — live in production, or test.
• <prefix> — a short public identifier used to look the token up.
• <secret> — the secret portion. Hoursmith stores only a hash of it, so the full token is shown once at creation and can never be retrieved again.

A first request

curl https://hoursmith.app/api/v1/me \
  -H "Authorization: Bearer hsk_live_..."

const res = await fetch('https://hoursmith.app/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.HOURSMITH_API_TOKEN}` },
});
const { data } = await res.json();
console.log(data.orgName, data.role, data.plan);

import os, requests

res = requests.get(
    "https://hoursmith.app/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['HOURSMITH_API_TOKEN']}"},
)
print(res.json()["data"])

The /me endpoint is the quickest way to verify a token — it returns the workspace, your role, plan, and scopes.

Keep tokens secret

• Store tokens in environment variables or a secrets manager — never in source control.
• Each token inherits the role of the member who created it. See Permissions & plans.
• All requests must use HTTPS.

Common authentication errors

See Errors for the full list.