Overview - Corsair

Use Timely through Corsair: one client, typed API calls, and incoming webhooks. Timely only offers OAuth 2.0; there are no API keys or personal access tokens. Register an app under Settings → API Access in Timely (https://app.timelyapp.com/<workspace id>/oauth_applications), then store its client ID and secret. Timely access tokens do not expire; refresh tokens rotate on every use. Every call is scoped to a workspace. Operations take an optional accountId; without one the plugin uses timely({ accountId }), then the account’s stored account_id, then the only workspace the token can reach. When the user belongs to several workspaces, pass accountId (from accounts.list). What you get:

36 typed API operations
12 incoming webhook event types

Setup

Install

npm install corsair @corsair-dev/timely

yarn add corsair @corsair-dev/timely

pnpm install corsair @corsair-dev/timely

bun add corsair @corsair-dev/timely

Add the plugin

corsair.ts

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { timely } from '@corsair-dev/timely';

export const corsair = createCorsair({
	plugins: [
		timely({
			accountId: 123456,
		}),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.

Choose authentication

OAuth 2.0 (Recommended)

Open hub.corsair.dev, navigate to your project, and enter the client ID and client secret from your Timely OAuth app.accountId is optional when the connected user has a single Timely workspace.

timely({
	accountId: 123456,
})

More: OAuth 2.0

Connect a tenant

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'timely',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

List this week’s time entries

const tenant = corsair.withTenant('acme');
await tenant.timely.api.timeEntries.list({ since: '2026-11-02', upto: '2026-11-08', per_page: 100 });

Log 1h 30m on a project

const tenant = corsair.withTenant('acme');
await tenant.timely.api.timeEntries.create({
	project_id: 987654,
	day: '2026-11-06',
	hours: 1,
	minutes: 30,
	note: 'Code review',
});

See the full list on the API page.

Webhooks

Timely sends a thin reference (entity_id, entity_type, date), not the full entry. Fetch the entry with timeEntries.get. Create the Timely webhook with a secret_token and store the same value as the account’s webhook_signature: unsigned deliveries are rejected.

timely({
    webhookHooks: {
        timeEntries: {
            created: {
                after: async (ctx, result) => {
                    console.log('Time entry logged:', result.data?.payload.entity_id);
                }
            },
        },
    },
})

Mount your framework handler once (see Frameworks), then point the provider at that URL. Full event list: Webhooks. Concepts: Webhooks, Hooks.

What’s next

API reference

Every timely.api.* operation with input and output types.

Webhooks

Event paths, payloads, and webhookHooks examples.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.

​Setup

​Example API calls

​Webhooks

​What’s next

API reference

Webhooks

Connect / OAuth

Use with agents

Setup

Example API calls

Webhooks

What’s next