# Authentication

> Access tokens, scopes, project-restricted tokens, service accounts, your organization's token policy, rotation.

**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**


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

**Python**


```python
from tasksmate import TasksMate

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

**tm**


```bash
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](https://tasksmate.indrasol.com/developers?dev=tokens) or with [`POST /v1/tokens`](https://developers.tasksmate.indrasol.com/reference/operations/tokenscreate/).
-   **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](https://developers.tasksmate.indrasol.com/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`](https://developers.tasksmate.indrasol.com/reference/operations/service-accountscreate/).
-   **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`](https://developers.tasksmate.indrasol.com/guides/errors/).

## Rotation

[Rotate: a new token with the same grant; the old one works 60 s more](https://developers.tasksmate.indrasol.com/reference/operations/tokensrotate/). Deploy the new token, then let the old one lapse. Revoke a leaked token at once — a revoked token answers [`token-revoked`](https://developers.tasksmate.indrasol.com/guides/errors/).

---
Source: https://developers.tasksmate.indrasol.com/guides/authentication/