API access

mTime exposes a REST API for developers who want to integrate with or automate the system. This page is a high-level orientation — the OpenAPI specification is the authoritative reference for every endpoint, request/response schema, and required permission. Endpoint-level detail is intentionally not repeated here.

Base URL

The API lives under the /api prefix of your workspace host — for example https://your-workspace.example/api. The API root (GET /api/) returns a plain identifier you can use as a health check.

Authentication

The API authenticates with API keys belonging to a service user.

1. In Admin › Users, create a service user and give it an API key. Copy the key immediately — it is shown only once.

2. Send the key on every request as a bearer token:

   Authorization: Bearer mtime_ak_...

The /me endpoint represents an interactive signed-in user and does not accept service-user keys. To verify a key works, call a data endpoint such as GET /api/employees.

OpenAPI specification

The full contract is published as OpenAPI 3.1:

• GET /api/openapi.yaml
• GET /api/openapi.json

Generate a typed client from it rather than hand-writing request types. Each operation also declares the permission it requires (x-required-permission), so you can see up front what role your service user needs.

API areas

Operations in the spec are grouped by tag; that grouping is authoritative. The main areas and their path prefixes:

The Settings and Admin areas are where most configuration and automation work happens; Me and Auth are oriented to interactive sessions rather than service-user keys.

Permissions

Every endpoint is gated by a permission (for example settings:create:*), resolved from the service user’s role. Some administrative actions — such as full data exports — require a higher role than ordinary configuration. If a call returns 403, check the operation’s required permission in the spec against the service user’s role.

The domain model

A few concepts underpin most of the API:

• Employment terms (the “agreement”) tie together everything that applies to an employee: the work-time norm, holiday calendar, time-off policies, allowance policies, a work-time policy, a settlement policy, available reasons, and the timesheet-approval mode. Assigning an employee to a term gives them the whole bundle.
• Activities are the categories time is registered against. Each has a type — work, timeoff, non-work, or allowance — and can be nested (a child must share its parent’s type). An activity can require a project and/or custom dimensions.
• Projects are work/billing buckets that registrations can be booked against, and can require a manager’s approval.
• Dimensions are custom tags (for example a vehicle or piece of equipment) with a defined set of allowed values. Activities can require them, which validates what users may pick.
• Timebank accounts hold balances — time off measured in days, or flex measured in hours.

Two layers of time

Time is recorded in two independent layers:

• Presence — check-in/out records. A presence interval carries a reason (and optionally a note and activity). The rule engine evaluates presence intervals.
• Entries — grid registrations that allocate time to an activity, a project, and dimension values.

By default these layers are independent; a work-time constraint can require that they reconcile. As a rule of thumb: when and why live on presence; what and where live on entries.

The rule engine

Premiums, overtime, on-call supplements and flex are calculated by policies built from plugins:

• Allowance policies turn worked time into a payable amount — either via a norm-aware week counter (overtime, flex/norm-delta, …) or via ordered rules (filters that select intervals + a calculator that scales them), optionally triggered by specific reasons, and registered onto a target allowance activity.
• Work-time policies enable flex tracking (linking a flex account), auto-registrations (such as a lunch deduction), and working-time constraints.
• Settlement policies are the period-close pipeline that banks counters into a timebank account and resolves payout versus flex.

Filters, calculators, counters, accruals, expirations, usage rules, holiday generators, and the various work-time and settlement steps are all plugins. Discover the available plugins and each one’s configuration schema at:

• GET /api/descriptor/plugins/
• GET /api/descriptor/plugins/{registry}/{plugin_id}/schema

Always read the descriptor before configuring a policy — it tells you the exact config keys and value types.

Configuration order

Because entities reference one another, create them foundation-first: holiday calendars, dimensions, timebank accounts and reasons → activities (allowance-target activities before the allowance policies that point at them) → allowance, work-time and settlement policies → employment terms → org units → employees → projects.

Effective-dated versioning

Configuration entities and employee records are versioned. A change takes effect from its effective date, and a newly created entity is not effective before its creation date. To change a past period, add a retroactive version rather than editing the current one.

How results are produced

Worked totals, allowances, flex and payout are not computed live on the daily timesheet — they materialize when a timesheet statement is generated and then submitted and approved (settlement). Statement generation runs as a scheduled batch job; the payout-versus-flex amount is chosen at submission. Build integrations that read settled figures from statements and account-movement reports accordingly.

Listing and scope

Collections are paginated and filterable (see each operation in the spec). Some user-centric lists default to the caller’s own data — for example timesheet statements default to the caller’s scope; request the workspace-wide scope explicitly when your integration needs it.