Appearance
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
| Flow | Best for |
|---|---|
| Authorization Code | Apps acting on behalf of users, with managed refresh |
| Unattended Access | Servers and scheduled jobs: connect once, stay connected on the refresh token |
| Client Credentials | Servers and jobs acting as the company, through its API user, with no sign-in |
| Device Code | CLIs 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
| Flow | Use case |
|---|---|
| Authorization Code | Web apps acting on behalf of users |
| Unattended Access | Servers and jobs acting as a particular person, connected once |
| Client Credentials | Servers and jobs acting as the company, no sign-in |
| Device Code | CLI tools, IoT, TVs |
3. Get an access token
Use the appropriate flow to obtain an access token from the token endpoint:
POST /oauth/tokenAccess 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
| Token | Lifetime | Notes |
|---|---|---|
| Access token, API audience | 1 hour | expires_in: 3600 |
| Access token, MCP audience | 8 hours | expires_in: 28800 |
| Refresh token | 14 days, sliding | Rotates on use; the old one is revoked. Issued to every client registered with the refresh_token grant |
| Grant | 60 days from consent | The 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
- v2 Overview — what v2 is and how it differs from v1
- Query Shape —
where/order/fields/scopes/since - Responses & Errors —
{ data, meta }, RFC 7807, validation issues - v2 API Reference — live endpoint reference
- MCP Server — connect Claude to Knowify for AI-powered data access