Skip to content

Unattended Access ​

A sync job, a backend or a scheduled report runs with nobody at the keyboard. There are two ways to give it access, and the choice is about whom it should act as:

  • As the company. A server-to-server app owned by your Knowify organization, created by one of its administrators, gets tokens with its own secret, no sign-in, and acts as the company's API user. Its owner is fixed once created. This is the usual choice for an integration.
  • As a particular person. The app connects the way a web app does: that person signs in once, and from then on your server keeps itself connected with the refresh token. This page is about that.

Either way the token acts for a Knowify user, the API user or the person, and what your server may see and do is what that user may see and do.

Connect once ​

  1. In the developer portal, create a Web app or server. Add a redirect URI your server or a small local script can receive, and choose the scopes it needs.
  2. Send an administrator of the Knowify account through the Authorization Code flow once. Only an administrator can authorize access to the account's data.
  3. Exchange the code for tokens and store the refresh token with the same care as the client secret.

A connection belongs to the person who made it

It ends when they leave the company or lose access. A connection that should outlive any one person is what the server-to-server app is for.

Stay connected ​

Access tokens last one hour. When one expires, or before each run, trade the refresh token for a new pair:

bash
curl -X POST https://developer.knowify.com/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"
json
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "a new refresh token",
  "scope": "projects:read invoices:read"
}

Keep the new refresh token and discard the old one. Every refresh returns a new one. Presenting an old refresh token again is treated as a leak and ends the connection.

javascript
async function refresh(store) {
  const response = await fetch('https://developer.knowify.com/oauth/token', {
    method: 'POST',
    headers: {
      Authorization: `Basic ${btoa(`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`)}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: await store.get() }),
  });
  if (!response.ok) throw new Error(`Reconnect needed: ${(await response.json()).error}`);
  const tokens = await response.json();
  await store.set(tokens.refresh_token);
  return tokens.access_token;
}

How long a connection lasts ​

There is no fixed end. A refresh token is good for 14 days, and each refresh starts a new 14 days, so a server that refreshes at least that often stays connected.

The connection ends, and an administrator has to connect again, when:

  • the server goes 14 days without refreshing
  • an old refresh token is presented again
  • the token is revoked
  • the app is deactivated in the developer portal
  • the Knowify user it acts for is deactivated or loses access

The token endpoint answers invalid_grant when the connection itself has ended and invalid_client for a deactivated app; API calls answer 401 once the user can no longer act.

Client credentials ​

A job that should act as the company rather than as a particular person uses the client_credentials grant instead: no sign-in, no connection to keep, no refresh token. See Client Credentials.