Skip to content
Developers

Use the client credentials flow

Client credentials authentication for server apps

Section titled “Client credentials authentication for server apps”

Use the OAuth 2.0 client credentials flow when a backend service or a third-party app needs to call the Tallyfy API with nobody logged in. It’s machine-to-machine sign-in.

You’ll need a Client ID and Client Secret from Tallyfy Support before you start.

How the client credentials flow worksGet ID and secretfrom Tallyfy SupportPOST /oauth/tokenApp tokenlasts 7 daysCall the APIas your appCreate the userif neededUser tokenlasts 3 monthsCall the APIas that user OnceOptionalThen ask forits tokenAsk againbefore expiry
  • Getting the Client ID and Client Secret from Tallyfy Support is the only manual step, and you do it once. You can’t automate it.
  • There are two kinds of token. An application token is for system jobs, like creating users. A user-specific token acts as one particular user, and it lasts longer: 3 months (7,776,000 seconds), against 7 days (604,800 seconds) for an application token.

Use it to build Tallyfy into your own software, so your users get workflow features without separate Tallyfy logins. It also suits system-level integrations, such as reporting and data sync, and automating process management or user provisioning.

Contact Tallyfy Support and describe your integration. They’ll give you a Client ID and Client Secret for your organization. Keep them somewhere safe.

First, your app needs its own access token. It uses this token for jobs like creating users or getting user-specific tokens.

  • Endpoint: POST https://go.tallyfy.com/api/oauth/token
  • Content-Type: application/x-www-form-urlencoded
  • Parameters:
    • grant_type: client_credentials
    • client_id: Your Client ID
    • client_secret: Your Client Secret
    • scope: * (optional)
const clientId = 'YOUR_CLIENT_ID';
const clientSecret = 'YOUR_CLIENT_SECRET';
const tokenUrl = 'https://go.tallyfy.com/api/oauth/token';
const params = new URLSearchParams();
params.append('grant_type', 'client_credentials');
params.append('client_id', clientId);
params.append('client_secret', clientSecret);
params.append('scope', '*');
const response = await fetch(tokenUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log('Access token:', data.access_token);
// Use data.access_token for subsequent API calls

Response:

{
"token_type": "Bearer",
"expires_in": 604800,
"access_token": "eyJ0eXAiOiJKV1Q..."
}

With your application token, you can create users in your organization:

  • Endpoint: POST https://go.tallyfy.com/api/applications/{orgID}/users
  • Headers:
    • Authorization: Bearer {your_app_access_token}
    • Content-Type: application/json
    • X-Tallyfy-Client: APIClient
  • Body fields:
    • first_name (required): Max 32 characters
    • last_name (required): Max 32 characters
    • email (required): Must be unique, valid domain
    • role (optional): admin, standard, or light
    • timezone (optional): User’s timezone string

To act as a specific user, use your application token to get a user-scoped token.

  • Endpoint: POST https://go.tallyfy.com/api/applications/{orgID}/users/{email}/token
  • Headers:
    • Authorization: Bearer {your_app_access_token}
    • X-Tallyfy-Client: APIClient
  • Note: No request body needed - the user’s email goes in the URL path.

Response:

{
"token_type": "Bearer",
"expires_in": 7776000,
"access_token": "eyJ0eXAiOiJKV1Q..."
}

Use either token (application-level or user-specific) in your API calls. Send these required headers:

  • Authorization: Bearer {token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient

All API endpoints follow the pattern https://go.tallyfy.com/api/organizations/{orgID}/....

For code examples of specific API calls, see the personal access token guide. The requests look the same. Just swap in your token.

  • Keep client credentials in an encrypted secrets manager, never in source code.
  • Guard the application token as closely as the secret. It can create users and get a token for any user in your organization.
  • A user-specific token lets whoever holds it act as that user for up to 3 months, so keep it out of browsers and logs.
  • If a Client Secret leaks, contact Tallyfy Support. They issue client credentials, so they’re the ones who can replace them.
  • Get a new application token before the 7-day expiry.