Appearance
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
- 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.
- Send an administrator of the Knowify account through the Authorization Code flow once. Only an administrator can authorize access to the account's data.
- 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.