Choosing Grants
When you create an organization API key, you choose the grants it carries, and that choice is permanent for the life of the key. This guide is how to pick the right set for what your integration does.
How grants work
A grant is a single named permission, like project.read or task.write. Each endpoint requires a specific grant, and a request whose key lacks it is refused even though the key itself is valid. Give a key the smallest set that covers its job: a key that leaks with three grants is a smaller problem than one that leaks with ten.
Start from what the integration does
Work backwards from the requests your integration will send.
Reading hours for reporting — timeentry.read and project.read.
Syncing a task board — task.read and task.write. The write grant covers everything on a task, including schedule, state, assignee, and archiving.
Reading task comments — comment.read.
Managing milestones — milestone.read and milestone.write.
Tracking invoices — billing.read, plus billing.status if the integration moves invoices to a new status.
Binding a webhook — the read grant for the event's family on the bound key: task.read for task events, billing.read for invoice events, and so on.
When a request embeds a related record, the key needs that resource's read grant too: expanding a project's client requires client.read, its members user.read, a task's comments comment.read.
Two families to know about
Epic endpoints check the task grants, so a key meant to work with epics needs task.read and task.write; the Epics grants in the picker aren't required by any endpoint. The calendar entry grants have no effect on an organization key, because calendar entries are reached with a personal access token instead; see Personal Access Tokens.
Replacing a key
When a key needs different grants, create the new key first, move your integration to it, then revoke the old one. Revocation takes effect immediately, and any webhooks bound to the revoked key stop delivering at the same moment.
The full grant table is on Authentication, and the grant each endpoint requires is listed with that endpoint in the API Reference.