Knowify OAuth Docs

Appearance

Getting Started ​

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

Placeholder URLs

Throughout these docs, developer.knowify.com and your-developers-portal-host are placeholders. Replace them with your actual deployment URLs. 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 auth path ​

Both reach the same endpoints. Pick based on your situation, not capability:

PathBest forSetup
OAuth 2.0Third-party apps acting on behalf of users; long-running integrations with managed refreshRegister a client, run a flow, exchange for tokens
Direct kAuthFirst-party scripts or jobs where you already hold a Knowify sessionJust send Authorization: kauth <token>

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
Client CredentialsServer-to-server (no user context)
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 5 days. Refresh tokens are valid for 10 days and rotate on use — together they give you a 10-day window of automated access before re-authenticating.

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.

Direct kAuth Quick Start ​

If you already have a kAuth session token:

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

That's it. No client registration, no flows, no token exchange. The token is granted the admin meta-scope (full read+write). Token lifecycle is your responsibility — see Direct kAuth.

Next Steps ​