Skip to content

Use the Client Credentials Flow

Overview

The OAuth 2.0 Client Credentials flow is designed for machine-to-machine authentication, typically used by third-party applications or backend services that need to interact with the Tallyfy API independently or on behalf of users within an organization.

This method requires you to first obtain a Client ID and Client Secret from Tallyfy Support.

Use cases

This integration pattern is ideal for organizations that want to:

  • Embed Tallyfy functionality within their own software.
  • Provide integrated workflow capabilities to their users without them needing separate Tallyfy logins visible in your app.
  • Automating process management or user provisioning programmatically.
  • System-level integrations (e.g., reporting, data synchronization).
  • Handle user provisioning programmatically

Steps

1. Request client credentials

  • Contact Tallyfy Support to request client credentials (Client ID and Client Secret).
  • Explain your integration needs.
  • Tallyfy will provide the credentials for your organization. Store them securely.

2. Obtain an application access token

Your application first needs its own access token to perform actions like user provisioning or getting user-specific tokens.

  • Endpoint: POST /oauth/token
  • Base URL: https://go.tallyfy.com/api (The primary API base URL).
  • OAuth Endpoint: https://go.tallyfy.com/api/oauth/token (Used specifically for getting the access token).
  • Request Body (form-data):
    • grant_type: client_credentials
    • client_id: Your Application’s Client ID
    • client_secret: Your Application’s Client Secret
    • scope: * (or specific scopes if provided by Tallyfy)
const fetch = require('node-fetch'); // If in Node.js environment
const FormData = require('form-data'); // If in Node.js environment
const clientId = 'YOUR_CLIENT_ID';
const clientSecret = 'YOUR_CLIENT_SECRET';
const tokenUrl = 'https://go.tallyfy.com/api/oauth/token';
const formData = new FormData();
formData.append('grant_type', 'client_credentials');
formData.append('client_id', clientId);
formData.append('client_secret', clientSecret);
formData.append('scope', '*'); // Optional, use specific scopes if needed
fetch(tokenUrl, {
method: 'POST',
body: formData,
// Headers for FormData are usually set automatically by fetch/browser
// but ensure Content-Type is 'application/x-www-form-urlencoded' if manually setting
})
.then(response => {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.json();
})
.then(data => {
console.log('Success:', data);
// Use data.access_token for subsequent API calls
})
.catch(error => {
console.error('Error fetching token:', error);
});

Response:

{
"token_type": "Bearer",
"expires_in": 3600, // Typically 1 hour
"access_token": "APP_LEVEL_ACCESS_TOKEN_EXAMPLE..."
}

3. Provision users programmatically (Optional)

Using the application-level token obtained in Step 2, you can manage users. Refer to the Members code samples section for specific examples once available. The general endpoint mentioned previously was POST /api/applications/{orgID}/users, but check the current Swagger definition for the correct endpoint, likely under /organizations/{org}/users/invite or similar, using the application token as the Bearer token.

4. Generate user-specific access tokens (Optional)

To act as a specific user, request a user-specific token using the application token.

  • Endpoint: POST /api/applications/{orgID}/users/{email}/token (Verify this endpoint with Tallyfy Support or Swagger spec; it might differ from standard OAuth patterns).
  • Base URL: Check with Tallyfy Support if this specific endpoint uses go.tallyfy.com or api.tallyfy.com.
  • Headers:
    • Authorization: Bearer {your_app_access_token} (From Step 2)
    • Content-Type: application/json
    • X-Tallyfy-Client: APIClient

Response:

{
"token_type": "Bearer",
"expires_in": 3600, // User token lifetime
"access_token": "USER_SPECIFIC_ACCESS_TOKEN_EXAMPLE..."
}

5. Make API requests as an application or user

Use the appropriate token (APP_LEVEL_ACCESS_TOKEN or USER_SPECIFIC_ACCESS_TOKEN) in the Authorization: Bearer {token} header for subsequent API calls, along with the standard Accept and X-Tallyfy-Client headers.

Example: Get tasks for a specific user (using user-specific token)

  • Endpoint: GET /organizations/{orgID}/me/tasks
  • Base URL: https://go.tallyfy.com/api
  • Resource Path: e.g., /organizations/{org_id}/users
  • Full URL: https://go.tallyfy.com/api/organizations/{org_id}/users
  • Headers:
    • Authorization: Bearer {user_specific_access_token}
    • Accept: application/json
    • X-Tallyfy-Client: APIClient

Code examples for making the requests themselves are similar to those shown in the Personal Access Token guide, just substitute the correct token.

Security considerations

  • Store client credentials securely (e.g., encrypted secrets management).
  • Protect both application-level and user-specific tokens.
  • Rotate secrets periodically.
  • Use HTTPS for all communications.
  • Implement robust token expiration and refresh logic.

Open Api > OAuth authorization flow for third-party applications

A comprehensive guide for implementing OAuth authorization flow in third-party applications that enables secure user authentication with Tallyfy through client IDs redirect URIs and access tokens while following security best practices and handling multi-organization scenarios.

Integrations > Open API

The Tallyfy REST API enables developers to build custom integrations access core platform features and automate workflows through secure authentication methods while adhering to rate limits and technical requirements for making API requests.

Open Api > Integrate with Tallyfy using the API

The Tallyfy REST API enables workflow integration through user-based or application-based authentication methods while supporting multi-organization contexts and providing webhooks for event-driven functionality.