Skip to content

Getting Started ​

The Knowify Developers API gives you programmatic access to projects, invoices, time entries, contracts, and everything else in a Knowify tenant.

URLs in these docs

The API lives at https://developer.knowify.com, and every example uses that host. your-developers-portal-host is a placeholder for the portal. For local development the API runs at http://localhost:4930 and the portal at http://localhost:4250.

Pick an API version ​

Two surfaces are currently active:

  • v2 — the active, recommended API. Unified query shape, RFC 7807 errors, OpenAPI-generated docs. Build here.
  • v1 — the legacy surface. Frozen — no new endpoints, kept alive for existing integrations.

See v2 Overview for the high-level shape.

Pick an OAuth flow ​

FlowBest for
Authorization CodeApps acting on behalf of users, with managed refresh
Unattended AccessServers and scheduled jobs: connect once, stay connected on the refresh token
Client CredentialsServers and jobs acting as the company, through its API user, with no sign-in
Device CodeCLIs and devices without a browser

OAuth Quick Start ​

1. Register and create a client ​

Sign up at the OAuth Portal, then navigate to Clients > Create Client. Configure:

  • Client Name — a label for your integration
  • Redirect URIs — where users are sent after authorization
  • Grant Types — the OAuth flows you'll use
  • Scopes — what data your app can access

Save the client secret — it's shown only once.

2. Choose an OAuth flow ​

FlowUse case
Authorization CodeWeb apps acting on behalf of users
Unattended AccessServers and jobs acting as a particular person, connected once
Client CredentialsServers and jobs acting as the company, no sign-in
Device CodeCLI tools, IoT, TVs

3. Get an access token ​

Use the appropriate flow to obtain an access token from the token endpoint:

POST /oauth/token

Access tokens are valid for 1 hour on the API (8 hours on the MCP server). Refresh tokens are valid for 14 days and rotate on each use, so an active integration keeps going; 60 days after the user's consent the grant ends and the user authorizes again in a browser. See Token lifetimes.

Token lifetimes ​

TokenLifetimeNotes
Access token, API audience1 hourexpires_in: 3600
Access token, MCP audience8 hoursexpires_in: 28800
Refresh token14 days, slidingRotates on use; the old one is revoked. Issued to every client registered with the refresh_token grant
Grant60 days from consentThe ceiling: refreshing stops here no matter how active the client was

4. Call the API ​

Include the token in the Authorization header:

bash
curl https://developer.knowify.com/api/v2/projects \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

v2 responses follow the { data, meta } shape for lists and return entities directly for single records — see Responses & Errors.

Next Steps ​