API usage as a third-party application instead of a user

Third-Party Application Integration with Tallyfy API

This guide explains how to integrate your application with Tallyfy using the client credentials flow. This allows your application to make API requests on behalf of your users.

Use cases for on-behalf-of access

This integration pattern is useful for organizations that want to:

• Embed Tallyfy functionality within their own software
• Provide integrated workflow capabilities to their users
• Automate process management for clients or employees
• Maintain an integrated user experience in their application
• Handle user provisioning programmatically

Implementation overview

Requirements

• Paid Tallyfy Professional or Enterprise subscription
• Client credentials (client ID and secret) from Tallyfy
• Basic understanding of OAuth 2.0 client credentials flow
• Development environment for testing API integration

Enterprise Feature

The client credentials grant type is only available to paid organizations and is not accessible during free trials. Contact Tallyfy Support to request access to this feature.

Step 1: Request client credentials

1. Contact Tallyfy Support to request client credentials for your organization
2. Provide details about your integration use case and requirements
3. Tallyfy will provision a client ID and secret specific to your organization
4. Store these credentials securely in your application environment

Step 2: Obtain application access token

To authenticate your application with Tallyfy, you must first obtain an application-level access token:

POST https://account.tallyfy.com/oauth/token

Request Body:

{
    "client_id": 12345,
    "client_secret": "hTWzy5rpYXcBn8K4J9PqEs2V...",
    "grant_type": "client_credentials",
    "scope": "*"
}

Response:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Token Expiration

Application access tokens typically expire after one hour. Your application should implement token refresh logic or request new tokens as needed.

Step 3: Provision users programmatically

With your application access token, you can create and manage users in your Tallyfy organization:

POST https://go.tallyfy.com/api/applications/{orgID}/users

Headers:

Authorization: Bearer {your_app_access_token}
Content-Type: application/json
X-Tallyfy-Client: APIClient

Request Body:

{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@yourcompany.com",
    "role": "standard",
    "timezone": "America/Chicago"
}

Available Roles:

• admin - Full organization administration access
• standard - Regular user with process creation capabilities
• light - Limited user who can only complete assigned tasks

Response:

{
    "id": 12345,
    "email": "john.smith@yourcompany.com",
    "first_name": "John",
    "last_name": "Smith",
    "role": "standard",
    "created_at": "2023-05-15T14:22:10.000Z"
}

Step 4: Generate user-specific access tokens

To perform actions on behalf of a specific user, you need to obtain a user-specific token:

POST https://go.tallyfy.com/api/applications/{orgID}/users/{email}/token

Headers:

Authorization: Bearer {your_app_access_token}
Content-Type: application/json
X-Tallyfy-Client: APIClient

Response:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 5: Make API requests on behalf of users

Use the user-specific token to make API requests as if they were made by the user:

GET https://go.tallyfy.com/api/organizations/{orgID}/me/tasks

Headers:

Authorization: Bearer {user_specific_access_token}
Content-Type: application/json
X-Tallyfy-Client: APIClient

Required Header

Always include the X-Tallyfy-Client: APIClient header in all direct API calls to Tallyfy endpoints. Requests without this header will be rejected.

Security considerations

When implementing on-behalf-of API access:

• Store client credentials in secure, encrypted storage
• Implement proper access controls to user tokens
• Rotate secrets periodically according to your security policies
• Validate that user emails belong to your organization before requesting tokens
• Use HTTPS for all API communication
• Implement token expiration handling and refresh logic

Troubleshooting

Error	Description	Solution
401 Unauthorized	Invalid client credentials	Verify client ID and secret
403 Forbidden	Insufficient permissions	Ensure the client has appropriate scopes
404 Not Found	User not found	Verify the user email and organization ID
429 Too Many Requests	Rate limit exceeded	Implement request throttling and retries

For assistance with this integration, contact Tallyfy Support with specific details about your use case and any error messages encountered.

Related articles

Open Api > Integrate with Tallyfy using the API

The Tallyfy REST API enables workflow automation through multiple authentication methods including user-based and application-based tokens while providing programmatic access to process management tasks and user administration features.

Open Api > API usage as a third-party application instead of a user

Organizations can seamlessly integrate Tallyfy into their applications by provisioning users and making API requests on their behalf through client credentials and user-specific access tokens.

Open Api > OAuth authorization flow for third-party applications

A comprehensive guide detailing the steps to implement OAuth authorization flow for third-party applications to securely authenticate users with Tallyfy through client IDs redirect URIs and access tokens while following security best practices.

Integrations > Open API

The Tallyfy REST API enables developers to integrate custom workflow solutions with extensive functionality through multiple authentication methods while providing programmatic access to core features like process management user administration and data analytics.