Timesheet API (1.0.0)

• Time Entry Management: Create, update, and delete time entries
• Project Management: Organize time entries by projects and clients
• Reporting: Generate detailed time reports across various dimensions
• User Management: Control access and permissions for team members

This API is ideal for integrating Timesheet with:

• Project management systems
• Accounting and invoicing software
• Custom dashboards and reporting tools
• Third-party productivity applications

All API requests require authentication using either:

• OAuth2 Bearer Token: For user-authorized applications
• API Key: For server-to-server integrations

API requests are limited to 100 requests per minute per API key.

timesheet.io implements the OAuth 2.0 protocol for secure authentication and authorization. This industry-standard protocol enables third-party applications to obtain limited access to user accounts without exposing sensitive credentials.

timesheet.io supports the following OAuth 2.0 grant types:

• Authorization Code Flow: For web applications and mobile apps
• Client Credentials: For server-to-server authentication
• Refresh Token: For maintaining long-term access

• All API requests must use HTTPS
• Access tokens must be sent in the Authorization header: Authorization: Bearer {token}
• Tokens expire after 24 hours
• Store client secrets securely and never expose them in client-side code
• Implement PKCE for mobile applications

Step 1: Create Application

Register your application at timesheet.io Developer Portal

Step 2: Obtain Credentials

After registration, you'll receive:

• client_id: Your application's public identifier
• client_secret: Your application's secret key (keep this secure!)
• redirect_urls: List of allowed callback URLs

GET https://api.timesheet.io/oauth2/auth

1. Authorization Request

Redirect users to our authorization endpoint:

GET https://api.timesheet.io/oauth2/auth

Required Parameters

2. Authorization Response

After user consent, we redirect to your redirect_uri with:

• code: Authorization code

3. Token Exchange

Exchange the authorization code for tokens:

POST https://api.timesheet.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

Required Parameters

Response

{
  "access_token": "eyJ0eXAi...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "def502..."
}

For server-to-server authentication without user context:

POST https://api.timesheet.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

Required Parameters

• Documentation
• Email: support@timesheet.io

timesheet.io supports API Key authentication as an alternative to OAuth 2.0 for programmatic access to your timesheet data. API Keys provide a simpler authentication method for server-to-server integrations and automated scripts.

• All API requests must use HTTPS
• API Keys must be sent in the Authorization header: Authorization: ApiKey {api_key}
• API Keys are long-lived but can be revoked at any time
• Store API Keys securely and never expose them in client-side code or version control
• Use separate API Keys for different applications or environments

Step 1: Access Developer Settings

Navigate to the Developer section in your Timesheet account at https://my.timesheet.io/development

Step 2: Create New API Key

Click "Create API Key" and provide:

• Name: A descriptive name for identification (e.g., "Production Integration", "Backup Script")
• Permissions: Scope of access for the API key (read-only, full access, etc.)
• Expiration: Optional expiration date for enhanced security

Step 3: Secure Your API Key

After creation, your API Key will be displayed only once:

• Format: ts_{prefix}.{secret} (e.g., ts_1a2b3c4d.9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f)
• Copy and store immediately - it cannot be retrieved later
• Store securely in environment variables or secure credential storage

Using ApiKey Authorization Format

Include your API Key in the Authorization header with the ApiKey scheme:

curl -H "Authorization: ApiKey ts_1a2b3c4d.9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f" \
     https://api.timesheet.io/v1/projects

JavaScript Example

const apiKey = 'ts_1a2b3c4d.9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f';

fetch('https://api.timesheet.io/v1/tasks', {
  headers: {
    'Authorization': `ApiKey ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Python Example

import requests

api_key = 'ts_1a2b3c4d.9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f'
headers = {
    'Authorization': f'ApiKey {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.timesheet.io/v1/timer', headers=headers)
data = response.json()

Listing API Keys

View all your API Keys in the developer settings to monitor usage and manage access.

Revoking API Keys

Immediately revoke API Keys that are:

• No longer needed
• Potentially compromised
• Associated with decommissioned applications

Best Practices

• Rotation: Regularly rotate API Keys (recommended: every 90 days)
• Principle of Least Privilege: Use read-only keys when write access isn't needed
• Environment Separation: Use different keys for development, staging, and production
• Monitoring: Monitor API Key usage for suspicious activity

Key Storage

• Never hardcode API Keys in source code
• Use environment variables or secure credential management systems
• Avoid logging API Keys in application logs

Access Control

• Set expiration dates for enhanced security
• Regularly audit API Key usage and permissions

Error Handling

API Key authentication errors return standard HTTP status codes:

• 401 Unauthorized: Invalid or expired API Key
• 403 Forbidden: API Key lacks required permissions
• 429 Too Many Requests: Rate limit exceeded

• API Key Management
• Documentation
• Email: support@timesheet.io

When you're making calls to the API, there'll be a lot of results to return. For that reason, we paginate the results to make sure responses are easier to handle.

We recommend you to set the limit parameter in every request to ensure you know how many results per page you'll get.

• If you set the limit to 10 and page to 1 you will get the results from 1-10.
• If you set the limit to 10 and page to 2, you'll get the results from 11-20.

All paginated responses include metadata about the total count, current page, and pagination settings:

{
  "items": [...],
  "count": 42,
  "page": 1,
  "limit": 10,
  "sort": "created",
  "order": "desc"
}

Webhooks allow you to receive real-time notifications about events in your Timesheet account. Instead of constantly polling our API, you can register a webhook URL that we'll call whenever specific events occur.

The API supports notifications for various events including:

• timer.start - When a timer is started
• timer.stop - When a timer is stopped
• task.create - When a new task is created
• task.update - When a task is updated
• project.create - When a new project is created

To create a webhook, provide a target URL and the event type you want to monitor. The target URL must be a valid HTTPS URL that responds to our verification request.

Webhook payloads are sent as JSON in the request body. Each payload includes:

• event - The event type that triggered the webhook
• timestamp - When the event occurred
• data - The full resource object related to the event

• Verify the authenticity of webhook requests by validating the signature in the headers
• Implement retry logic for temporary failures
• Respond with 2xx status codes to acknowledge receipt

The Profile API allows you to manage user profiles, including personal information, preferences, and account settings.

• Retrieve current user profile information
• Update profile details like name, email, and image
• Manage account deletion and data privacy

Profiles can be associated with multiple organizations and teams. The APIs provide ways to view and manage these relationships.

The API provides endpoints specifically for data privacy compliance, allowing users to exercise their right to delete personal data or their entire account.

The Settings API lets users customize their Timesheet experience by managing preferences and defaults.

Special settings control the timer behavior:

• timerRounding - Round timer times to nearest interval
• timerRoundingType - How to round (up, down, nearest)
• pauseRounding - Round pause times to nearest interval

The Organization API handles the creation and management of organizational entities that represent businesses or departments. Organizations provide an overarching structure above teams for administrative and billing purposes.

Organizations include:

• Basic information (name, description, etc.)
• Branding elements (image, color)
• Membership with permission levels
• Subscription and billing information

Organizations use a permission system:

• Admin: Full control over the organization
• Invoicing: Permission to manage invoices and documents
• Billing: Permission to view and manage billing information

The API provides endpoints to:

• Add members to an organization
• Update member permissions
• Remove members
• List and search organization members

Organizations can contain multiple teams:

• Teams inherit organization settings
• Organization members can access teams based on permissions
• Teams can be created within the organization context