Public API v1.0 (legacy)

API v1.0 is a read-mostly interface to a limited slice of Uku, authenticated with a token that lasts ten minutes, kept running for integrations built before v3 existed.

Issuing and managing v1.0 API key pairs is open to Company Owners and Company Admins on the Elite plan.

API v1.0 gives you access to:

• Clients — list, filter, and create clients
• Contacts — look up one contact by its id, or by client and email address, and create contact persons linked to clients. There is no contact list endpoint and no paging on contacts
• Client groups — read client group structures
• Client fields — read the custom field definitions set up for clients; each client’s own values come back on the client record itself
• Tasks — list, filter, and create tasks
• Task fields — read the custom field definitions set up for tasks; each task’s own values come back on the task record itself
• Time entries — query tracked time data
• Members — list team members
• Member groups — read member group structures
• Invoices — query invoice data
• Contracts — query contract data
• Products — list products
• Product fields — read the billing reference lists products draw on, such as articles, resources, cost centers, and projects
• Invoice sellers — read invoice seller profiles
• Topics — list task topics
• Webhooks — subscribe a URL to the new-client and new-contact events

Responses are JSON. v1.0 is mostly a reading API: only clients, contacts, tasks, and webhook subscriptions can be created, nothing can be updated, and the only thing you can delete is a webhook subscription (to unsubscribe). If you need to write back to Uku, use API v3.

Webhooks you subscribed through v1.0 keep firing, and they fire on one narrow trigger: a client or a contact created in the Uku web app. A record created through the API itself, by an import or an automation, or through the Client Portal produces no v1.0 delivery. v3 runs a separate webhook engine with its own event set and payload format, so moving to v3 leaves the subscriptions you already have untouched — and a v1.0 subscription keeps sending its original flat payload rather than switching to the v3 one.

The Public API is an app you switch on for your company, like the rest of Uku’s integrations.

Path: Settings & Apps

1. Find the Public API card. The apps are grouped under Setup, Power up and Integrations; Public API sits with the integrations, and carries an Elite chip because it’s an Elite feature.
2. Open the app and activate it for your company.

A v1.0 credential is a pair — an API key and an API secret — and you can hold several pairs at once, one per integration.

Path: Settings & Apps → Public API → (old) API

1. Open the Public API app and go to the (old) API tab.
2. Enter a Name for your API key pair (for example, “Reporting tool” or “Zapier integration”).
3. Click Generate new API KEY.
4. Your new API key and API secret appear in the table. Use the copy button to copy each value.

Delete a key pair by clicking the trash icon in the table. That blocks new sign-ins with those credentials straight away, but it does not kill a token that has already been issued: a v1.0 token is checked on its signature and its expiry alone, so one minted just before the delete keeps working until it runs out. This is exactly where v1.0 differs from API v3, where revoking a key does cut access off immediately. If a v1.0 secret has leaked, delete the pair and then treat the following ten minutes as still exposed.

Send a POST request to the login endpoint with your API key and secret:

POST https://app.getuku.com/api/v1.0/login
Content-Type: application/json

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret"
}

The response contains a JWT token:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Include the token in the Authorization header for all subsequent requests:

GET https://app.getuku.com/api/v1.0/clients
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokens expire after 10 minutes. When a token expires, authenticate again to get a new one. Design your integration to handle re-authentication automatically.

The interactive API documentation for v1.0 is at app.getuku.com/docs/sandbox/. You can test endpoints, see request and response schemas, and try queries directly from your browser. Note that the webhook subscription endpoint is not listed there — it exists, but the sandbox doesn’t document it.

A v1.0 key pair reaches your company’s live data and its secret stays readable in Uku, so look after it the way you would look after a password.

• Keep your API secret confidential. Treat it like a password. Never commit it to version control or share it in plain text.
• Use separate key pairs for different integrations. If one is compromised, revoke its key without affecting others.
• Tokens are short-lived. The 10-minute expiration window limits exposure if a token is intercepted.
• Delete unused keys. If you decommission an integration, remove its API key pair immediately.
• Always call over HTTPS. The API base URL is served over TLS; never send your key, secret, or token over plain HTTP.

A v1.0 key acts as the person who created it. The token it returns carries that person’s identity as well as the company’s, and the services behind the API apply that person’s own access rights — so two key pairs in the same company can legitimately return different data, depending on which clients each creator can see. It also means the key stops working when its creator does: once that person is no longer a member of the company, POST /login fails outright and the integration goes dark even though the key pair is still sitting in the table. When somebody leaves, check which integrations ran on their key and re-issue those pairs under someone who stays.

Moving an integration to API v3 is mostly a change to how you authenticate, and you can do it one endpoint at a time. Generate a v3 key in the same Public API app, then drop the POST /login call entirely — v3 has no token exchange, so there is no expiry to handle and no re-authentication loop to write. Each request carries two headers instead of a Bearer token; the Public API v3 article covers them.

Both key types stay active at the same time, so you can move one endpoint across, confirm it against real data, and leave the rest of the integration on v1.0 until you’re ready. Resource names are close but not identical between the two versions, so check each one against the interactive documentation at app.getuku.com/api/v3/docs rather than assuming the v1.0 path carries over.