Authentication

Every request carries a credential in the Authorization header. AbleTime has two kinds, and they answer different questions: an API key acts for your organization, and a personal access token (PAT) acts for one person.

http

Authorization: Bearer <your-credential>

Organization API keys

An API key is the credential most integrations use. It belongs to the organization rather than to whoever created it, so it keeps working when people join or leave.

Creating one

Go to Settings > Integrations > API Keys and add a key. You choose its name, the grants it carries, and optionally an expiry date.

The key is shown once, at the moment you create it. AbleTime stores only a hash of it and cannot show it again. Copy it straight into your secret store; if you lose it, revoke the key and create another.

Afterwards the list shows each key's name, key prefix (a short non-secret fragment that lets you tell keys apart), grants, status, creation date and expiry. Revoking a key takes effect immediately and also stops any webhooks bound to that key.

Grants

A grant is a single named permission. A key carries a fixed set of them, chosen when you create it, and every endpoint states which grant it requires. A key with no grant for an endpoint is refused with 403 even though the key itself is perfectly valid.

Grant	Allows
`timeentry.read`	Reading time entries and timers, and binding webhooks for timeentry events in Settings → Integrations → Webhooks (the bound key needs timeentry.read)
`timeentry.write`	Creating, updating and deleting time entries, and operating timers
`task.read`	Reading tasks, and reading epics, and binding webhooks for task and epic events in Settings → Integrations → Webhooks (the bound key needs task.read)
`task.write`	Creating and updating tasks, everything on a task, and creating and updating epics
`milestone.read`	Reading milestones, and binding webhooks for milestone events in Settings → Integrations → Webhooks (the bound key needs milestone.read)
`milestone.write`	Creating, updating and deleting milestones
`comment.read`	Including a task's comments via `expand=comments`, and binding webhooks for comment events in Settings → Integrations → Webhooks (the bound key needs comment.read)
`billing.read`	Reading invoices, and binding webhooks for invoice events in Settings → Integrations → Webhooks (the bound key needs billing.read)
`billing.status`	Moving an invoice to a new status
`project.read`	Reading projects
`client.read`	Reading clients, and expanding a project's client
`user.read`	Reading users, and expanding a project's members
`calendarentry.read`	Reading calendar entries, with a personal access token
`calendarentry.write`	Writing calendar entries, with a personal access token

Give a key the smallest set that does its job. A key that only reports on hours needs reading grants and nothing else.

Epics are governed by the task grants, not by grants of their own. Reading an epic needs task.read; creating, updating, deleting or changing the state of one needs task.write.

Personal access tokens

A personal access token belongs to one person. Each person mints their own from their profile, under API Access, and holds at most one at a time; rotating replaces the old token immediately.

A token carries that person's identity and their role in the organization. It carries no grants at all, because what it may do is decided by who its holder is and by which projects they belong to, exactly as it would be in the application.

Personal access tokens exist for work that is inherently about one person. Calendar entries are the clearest case: they hold proposed time a person has not yet committed, so they are reachable only with that person's own token, never with an organization key.

Your organization must also have agent access enabled for personal access tokens to work. Without it a valid token is refused.

Choosing between them

	API key	Personal access token
Acts for	The organization	One person
Prefix	`atk_`	`apt_`
Created in	Settings > Integrations > API Keys	Your profile, under API Access
How many	As many as you need	One per person
Permissions	The grants you assign	The holder's role and project membership
Survives the creator leaving	Yes	No
Reaches calendar entries	No	Yes

When authentication fails

Status	Code	What it means
401	`INTEGRATION_KEY_MISSING`	No Authorization header, or it is not a bearer token
401	`INTEGRATION_KEY_INVALID`	The credential is unknown, revoked or expired
403	`INTEGRATION_PLAN_REQUIRED`	The credential is fine, but the organization's plan does not include API access
403	`INTEGRATION_GRANT_MISSING`	The key is valid but lacks the grant this endpoint requires
403	`INTEGRATION_PAT_REQUIRED`	This endpoint takes a personal access token and an organization key was sent
403	`INTEGRATION_AGENT_ACCESS_DISABLED`	The organization has not enabled agent access

A refusal never tells you which of unknown, revoked or expired applies. That is deliberate, so a caller probing with guessed credentials learns nothing from the difference.