TimeTracker/docs/api/API_TOKEN_SCOPES.md

API Token Scopes Reference

Overview

API tokens use scopes to control access to resources. When creating a token, you select which scopes to grant. This document explains each scope and when to use it.

Scope Format

Scopes follow the format: action:resource

• action: read or write
• resource: The resource type (e.g., projects, time_entries)

Special scopes:

• admin:all - Full administrative access to all resources
• * - Wildcard (admin only)

Available Scopes

Projects

read:projects

Grants: View project information
Endpoints:

• GET /api/v1/projects - List projects
• GET /api/v1/projects/{id} - Get project details

Use Cases:

• Read-only integrations
• Reporting tools
• Dashboard displays
• Project status monitors

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-domain.com/api/v1/projects

write:projects

Grants: Create, update, and archive projects
Endpoints:

• POST /api/v1/projects - Create project
• PUT /api/v1/projects/{id} - Update project
• DELETE /api/v1/projects/{id} - Archive project

Use Cases:

• Project management integrations
• Automated project creation
• Bulk project updates
• Project lifecycle automation

Example:

curl -X POST https://your-domain.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Project", "status": "active"}'

Inventory: Dedicated scopes read:inventory and write:inventory grant access only to inventory endpoints. For backward compatibility, read:projects and write:projects also grant the same inventory access.

• read:inventory (or read:projects): GET /api/v1/inventory/items, GET /api/v1/inventory/warehouses, GET /api/v1/inventory/stock-levels, GET /api/v1/inventory/transfers, GET /api/v1/inventory/transfers/{reference_id}, GET /api/v1/inventory/reports/*, suppliers, purchase orders (read).
• write:inventory (or write:projects): POST /api/v1/inventory/transfers, POST /api/v1/inventory/movements, create/update/delete items, suppliers, purchase orders.

Use read:inventory / write:inventory when you need inventory-only tokens (least privilege).

---

Time Entries

read:time_entries

Grants: View time entries and timer status
Endpoints:

• GET /api/v1/time-entries - List time entries
• GET /api/v1/time-entries/{id} - Get time entry details
• GET /api/v1/timer/status - Get timer status

Use Cases:

• Timesheet exports
• Reporting and analytics
• Invoice generation
• Time tracking dashboards

Permissions:

• Non-admin users can only see their own time entries
• Admin users can see all time entries

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://your-domain.com/api/v1/time-entries?start_date=2024-01-01"

write:time_entries

Grants: Create, update, and delete time entries; control timer; timesheet periods and time-off requests
Endpoints:

• POST /api/v1/time-entries - Create time entry (optional Idempotency-Key header for safe retries)
• POST /api/v1/time-entries/import-csv - Import time entries from CSV (multipart file or JSON/raw body)
• POST /api/v1/time-entries/bulk - Bulk delete, billable/paid flags, or tag add/remove
• PUT /api/v1/time-entries/{id} - Update time entry
• DELETE /api/v1/time-entries/{id} - Delete time entry
• POST /api/v1/timer/start - Start timer
• POST /api/v1/timer/stop - Stop timer
• DELETE /api/v1/timesheet-periods/{id} - Delete timesheet period (draft/rejected only; owner or admin)
• DELETE /api/v1/time-off/requests/{id} - Delete time-off request (draft/submitted/cancelled; owner or approver)

Use Cases:

• Time tracking integrations
• Automated time entry creation
• Timer control from external apps
• Bulk time entry updates

Example:

curl -X POST https://your-domain.com/api/v1/timer/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 1}'

---

Tasks

read:tasks

Grants: View task information
Endpoints:

• GET /api/v1/tasks - List tasks
• GET /api/v1/tasks/{id} - Get task details

Use Cases:

• Task management integrations
• Kanban board displays
• Progress tracking
• Task reporting

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://your-domain.com/api/v1/tasks?project_id=1&status=todo"

write:tasks

Grants: Create, update, and delete tasks
Endpoints:

• POST /api/v1/tasks - Create task
• PUT /api/v1/tasks/{id} - Update task
• DELETE /api/v1/tasks/{id} - Delete task

Use Cases:

• Task synchronization
• Automated task creation
• Task status updates
• Project planning automation

Example:

curl -X POST https://your-domain.com/api/v1/tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Task", "project_id": 1, "status": "todo"}'

---

Clients

read:clients

Grants: View client information
Endpoints:

• GET /api/v1/clients - List clients
• GET /api/v1/clients/{id} - Get client details

Use Cases:

• CRM integrations
• Client directories
• Invoice generation
• Contact management

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-domain.com/api/v1/clients

write:clients

Grants: Create, update, and delete clients
Endpoints:

• POST /api/v1/clients - Create client
• PUT /api/v1/clients/{id} - Update client
• DELETE /api/v1/clients/{id} - Delete client

Use Cases:

• Client data synchronization
• CRM integration
• Automated client onboarding
• Contact management

Example:

curl -X POST https://your-domain.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Client", "email": "client@example.com"}'

---

Quotes

read:quotes

Grants: List and view quotes
Endpoints:

• GET /api/v1/quotes - List quotes
• GET /api/v1/quotes/{id} - Get quote details

Use Cases:

• Client portal and CRM read integrations
• Quote status dashboards
• External systems that only need quote visibility

write:quotes

Grants: Create, update, and delete quotes
Endpoints:

• POST /api/v1/quotes - Create quote
• PUT /api/v1/quotes/{id} - Update quote
• DELETE /api/v1/quotes/{id} - Delete quote

Use Cases:

• Quote generation from external systems
• Automated quote updates and status sync
• Back-office quote lifecycle tools

---

Invoices

read:invoices

Grants: List and view invoices via the versioned API
Endpoints (non-exhaustive; see OpenAPI at /api/docs when enabled):

• GET /api/v1/invoices — List invoices
• GET /api/v1/invoices/{id} — Get invoice by id

Use Cases:

• Billing dashboards and exports
• Integrations that sync invoice status

write:invoices

Grants: Create and update invoices via the versioned API
Endpoints (non-exhaustive):

• POST /api/v1/invoices — Create invoice (JSON body)
• PUT / PATCH /api/v1/invoices/{id} — Update invoice
• DELETE /api/v1/invoices/{id} — Cancel invoice
• POST /api/v1/clients/{client_id}/invoice-unbilled — Create a draft invoice from all unbilled billable time for that client (line items grouped by project). Requires write:invoices when using an API token; the browser UI uses a logged-in session with Create invoices permission instead. Successful response JSON: invoice_id, invoice_number, total, item_count. Returns 400 when there is no unbilled time, or when any unbilled entry has no project_id (assign entries to a project first).

Use Cases:

• Automated billing from integrations
• One-shot “invoice everything open” for a client (API or client detail page)

Example (API token):

curl -X POST "https://your-domain.com/api/v1/clients/42/invoice-unbilled" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

---

Reports

read:reports

Grants: Access reporting and analytics endpoints; read leave types and holidays
Endpoints:

• GET /api/v1/reports/summary - Get summary reports
• GET /api/v1/time-off/leave-types - List leave types
• GET /api/v1/time-off/holidays - List company holidays

Use Cases:

• Business intelligence tools
• Custom reporting
• Analytics dashboards
• Management reporting

Permissions:

• Non-admin users can only see their own data
• Admin users can see all data

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://your-domain.com/api/v1/reports/summary?start_date=2024-01-01&end_date=2024-01-31"

write:reports

Grants: Create and delete leave types and company holidays (workforce admin)
Endpoints:

• POST /api/v1/time-off/leave-types - Create leave type (admin only)
• DELETE /api/v1/time-off/leave-types/{id} - Delete leave type (admin only; blocked if it has time-off requests)
• POST /api/v1/time-off/holidays - Create company holiday (admin only)
• DELETE /api/v1/time-off/holidays/{id} - Delete company holiday (admin only)

Permissions: Admin only for these endpoints.

---

Users

read:users

Grants: View user information
Endpoints:

• GET /api/v1/users/me - Get current user
• GET /api/v1/users - List all users (admin only)

Use Cases:

• User directory
• Profile information
• User management
• Team listings

Permissions:

• All users can access /users/me
• Only admins can access /users (requires admin:all)

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-domain.com/api/v1/users/me

---

Administrative

admin:all

Grants: Full administrative access to all resources
Endpoints: All API endpoints

Use Cases:

• Admin automation scripts
• System integrations
• Backup tools
• Migration scripts

⚠️ Warning: This scope grants complete access. Use with extreme caution.

Example:

# Admin can access all user data
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-domain.com/api/v1/users

---

Scope Combinations

Common Combinations

1. Read-Only Access

read:projects
read:time_entries
read:tasks
read:clients
read:reports

Use For: Dashboards, reporting tools, read-only integrations

2. Time Tracking Integration

read:projects
read:time_entries
write:time_entries
read:tasks

Use For: Time tracking apps, timer integrations

3. Project Management Integration

read:projects
write:projects
read:tasks
write:tasks
read:time_entries

Use For: Project management tools, task synchronization

4. Full User Access (Non-Admin)

read:projects
write:projects
read:time_entries
write:time_entries
read:tasks
write:tasks
read:clients
write:clients
read:quotes
write:quotes
read:reports

Use For: Personal automation, full-featured integrations

5. Admin Access

admin:all

Use For: Administrative tools, system automation

Scope Checking

How Scope Checking Works

1. Token Authentication: API validates the token
2. Scope Verification: Checks if token has required scope
3. Resource Access: Verifies access to specific resource
4. User Permissions: Applies user-level permissions

Wildcard Scopes

The API supports wildcard patterns:

• read:* - Read access to all resources
• write:* - Write access to all resources
• * - Full access (equivalent to admin:all)

Note: Wildcards are only available for admin users.

Security Best Practices

Principle of Least Privilege

1. Grant minimum scopes needed for the integration
2. Avoid admin:all unless absolutely necessary
3. Create separate tokens for different integrations
4. Review scopes regularly and revoke unused permissions

Token Management

1. Separate tokens per integration:

   Token 1: Time tracking app (read:projects, write:time_entries)
   Token 2: Reporting tool (read:*, read:reports)
   Token 3: Admin script (admin:all)
   

2. Set expiration dates for temporary integrations

3. Monitor token usage in the admin dashboard

4. Rotate tokens periodically (create new, delete old)

Scope Audit

Regularly review tokens and their scopes:

1. Navigate to /admin/api-tokens
2. Review each token's scopes
3. Remove unused scopes
4. Delete inactive tokens

Examples by Use Case

Dashboard Integration

Requirements: Display time tracking statistics
Scopes:

read:projects
read:time_entries
read:reports

Why:

• read:projects - Show project names and details
• read:time_entries - Display time entries
• read:reports - Generate statistics

Mobile Timer App

Requirements: Start/stop timer, create time entries
Scopes:

read:projects
read:tasks
read:time_entries
write:time_entries

Why:

• read:projects - Select project for timer
• read:tasks - Select task (optional)
• read:time_entries - Show existing entries
• write:time_entries - Start/stop timer, create entries

Invoice Generator

Requirements: Read time entries and generate invoices (read-only reporting), or call the invoice unbilled API (writes a draft invoice)
Scopes (read-only path):

read:projects
read:clients
read:time_entries
read:reports

Why:

• read:projects - Get project rates
• read:clients - Get client billing information
• read:time_entries - Get billable hours
• read:reports - Generate summaries

To create a draft invoice from all unbilled time for one client via POST /api/v1/clients/{client_id}/invoice-unbilled, add write:invoices (and keep read:clients / read:projects as needed for your workflow). The Clients and Invoices modules must be enabled for the token’s user.

Project Management Sync

Requirements: Two-way sync with external PM tool
Scopes:

read:projects
write:projects
read:tasks
write:tasks
read:time_entries

Why:

• read:projects / write:projects - Sync projects
• read:tasks / write:tasks - Sync tasks
• read:time_entries - Import time tracking

Testing Scopes

Test Token Scopes

1. Create a test token with limited scopes
2. Try accessing different endpoints
3. Verify proper authorization

Example:

# Create token with only read:projects

# This should work:
curl -H "Authorization: Bearer TOKEN" \
     https://your-domain.com/api/v1/projects

# This should fail (403):
curl -X POST https://your-domain.com/api/v1/projects \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test"}'

Troubleshooting

"Insufficient permissions" Error

Cause: Token lacks required scope
Solution:

1. Check error message for required_scope
2. Create new token with needed scope
3. Update integration to use new token

Example Error:

{
  "error": "Insufficient permissions",
  "message": "This endpoint requires the 'write:projects' scope",
  "required_scope": "write:projects",
  "available_scopes": ["read:projects", "read:time_entries"]
}

Access Denied for Specific Resource

Cause: User permissions restrict access
Solution:

• Non-admin users can only access their own resources
• Use admin token for cross-user access
• Verify user has permission to access resource

Reference Table

Scope	Read	Write	Admin Required	Notes
read:projects	✅	❌	❌	View projects (and inventory read)
write:projects	✅	✅	❌	Manage projects (and inventory write)
read:inventory	❌	❌	❌	View inventory only
write:inventory	❌	❌	❌	Manage inventory only
read:time_entries	✅	❌	❌	View own entries
write:time_entries	✅	✅	❌	Manage own entries
read:tasks	✅	❌	❌	View tasks
write:tasks	✅	✅	❌	Manage tasks
read:clients	✅	❌	❌	View clients
write:clients	✅	✅	❌	Manage clients
read:quotes	✅	❌	❌	View quotes
write:quotes	✅	✅	❌	Manage quotes
read:reports	✅	❌	❌	View own reports
read:users	✅	❌	Partial	/users/me for all, /users admin only
admin:all	✅	✅	✅	Full access

Need Help?

• 📖 API Documentation: docs/REST_API.md
• 🚀 Quick Start: docs/REST_API_QUICKSTART.md
• 🔍 Interactive Docs: /api/docs
• 📋 Implementation Summary: REST_API_IMPLEMENTATION_SUMMARY.md