API Tokens

API tokens let you access the TaskView API without a browser session. Use them for scripts, CI/CD pipelines, bots, and any programmatic integration.

Token format

Tokens use the prefix tvk_ followed by 64 hex characters:

tvk_a1b2c3d4e5f6...

The full token is shown only once at creation. TaskView stores only the SHA-256 hash - if you lose the token, you'll need to create a new one.

Creating a token

1. Go to Account Settings → API Tokens
2. Click "Create Token"
3. Enter a name (e.g. "CI pipeline", "Slack bot")
4. Optionally restrict permissions and projects
5. Optionally set an expiration date
6. Click "Create"
7. Copy the token immediately - it will not be shown again

Authentication

Send the token in the Authorization header:

curl -H "Authorization: Bearer tvk_a1b2c3d4..." \
  https://your-instance.com/module/tasks?goalId=1

Permission scoping

By default a token inherits all permissions of its owner. You can restrict this at creation:

• Permissions - select which operations the token can perform (e.g. only read tasks, only create tasks)
• Projects - restrict the token to specific projects. If no projects are selected, the token has access to all projects the owner can access

Permissions are intersected with the user's RBAC role. A token cannot have more permissions than the user who created it. See Roles and Permissions for details on how RBAC works.

Available permission examples

The full list of available permissions is returned by GET /module/api-tokens/permissions.

Expiration

Tokens can optionally have an expiration date. After expiration, the token returns 401 Unauthorized. Tokens without an expiration date are valid until manually revoked.

Security

• Tokens cannot manage other tokens - all token management endpoints reject API token authentication
• Only the SHA-256 hash is stored in the database
• lastUsedAt is updated on each use for audit purposes
• Tokens for blocked users are automatically rejected

API reference

All endpoints require JWT authentication (not API token).

List tokens

GET /module/api-tokens

Returns all tokens for the current user (without hashes).

Create token

POST /module/api-tokens

{
  "name": "CI pipeline",
  "allowedPermissions": ["component_can_watch_content"],
  "allowedGoalIds": [1, 2],
  "expiresAt": "2026-12-31T23:59:59Z"
}

All fields except name are optional. Returns the full plaintext token once.

Delete token

DELETE /module/api-tokens

{
  "id": 5
}

List available permissions

GET /module/api-tokens/permissions

Returns permissions grouped by category.

Usage example

Using the taskview-api package:

npm install taskview-api axios

import axios from 'axios'
import { TvApi } from 'taskview-api'

const GOAL_ID = 1

const $axios = axios.create({
  baseURL: 'https://your-instance.com',
  headers: {
    Authorization: 'Bearer tvk_your_token_here',
  },
})

const api = new TvApi($axios)

// Fetch all tasks in a project
const tasks = await api.tasks.fetch({ goalId: GOAL_ID })
console.log(`Found ${tasks.length} tasks`)

// Create a new task
const newTask = await api.tasks.createTask({
  goalId: GOAL_ID,
  description: 'Task created via API',
})
console.log('Created task:', newTask.id)

// Update the task description
await api.tasks.updateTask({
  id: newTask.id,
  description: 'Updated via API',
})
console.log('Task updated')

// Fetch projects
const goals = await api.goals.fetchGoals()
console.log('Projects:', goals.map((g) => g.name))