Authentication

What this is: how a request proves who it is — a bearer access token. When you need it: on every call except the health check.

curl

curl "$TASKSMATE_API_URL/v1/me" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN"

Python

from tasksmate import TasksMate

tm = TasksMate(token="…")   # or TASKSMATE_TOKEN
print(tm.me())

tm

tm auth login   # asks for the token, checks it, stores it
tm auth status

A token acts for one principal, in one organization, within its scopes

Access tokens

Send Authorization: Bearer <token>. A token’s kind is live (tm_live_…) or test (tm_test_…: authenticates and reads, never writes)

• Mint one in Developers → Tokens or with POST /v1/tokens.
• One organization per token.
• Projects: Restrict the token to these projects (and their tasks; no unfiled task). Omit / null = every project the principal can reach.

Scopes

Each operation in the reference shows the scope it needs. admin implies every scope, and <ns>:write implies <ns>:read.

Scope	Grants
tasks:read	Read tasks, their comments, attachments, history, sections and saved views.
tasks:write	Create, update and delete tasks, comments, attachments, sections and saved views (implies tasks:read).
projects:read	Read projects, their members, resources, statistics, goals and roadmaps.
projects:write	Create, update and delete projects, their members, resources and goals (implies projects:read).
teams:read	Read teams, their members, sprints, milestones and availability.
teams:write	Create, update and delete teams, their members, sprints, milestones and availability (implies teams:read).
org:read	Read the organization, its settings, members, invites, designations, access tokens and access review.
org:write	Change the organization's settings, members, invites and designations; mint, rotate and revoke access tokens and service accounts (implies org:read).
webhooks:read	Read the organization's webhooks and their delivery logs (owner / admin, or a service account).
webhooks:write	Create, change, pause, test, rotate and delete webhooks and replay deliveries (implies webhooks:read).
admin	Every scope, including the audit log.

Service accounts

A service account is a member of your organization that cannot sign in. It exists to hold tokens, so an integration keeps working when a person leaves.

• Create one (owners and admins): POST /v1/organizations/{org_id}/service-accounts.
• Mint its tokens with principal_user_id: Act as a SERVICE ACCOUNT of this org (owner / admin only). Omit = yourself.

Your organization’s token policy

Owners and admins set it in the organization settings:

• allow_personal_tokens — Whether members may mint personal access tokens (default true; service-account tokens are unaffected).
• require_token_expiry — Whether every new token must carry an expires_at (default false).
• max_token_ttl_days — The longest lifetime a new token may have, in days; send null for no cap (the default).

A token the policy refuses fails with token-policy.

Rotation

Rotate: a new token with the same grant; the old one works 60 s more. Deploy the new token, then let the old one lapse. Revoke a leaked token at once — a revoked token answers token-revoked.