OAuth authorization flow for third-party applications

Implementing the OAuth authorization flow

This guide explains how to implement a standard OAuth authorization flow for third-party applications integrating with Tallyfy. This approach allows your users to authenticate directly with Tallyfy without sharing their credentials with your application.

Requirements

Paid Tallyfy Professional or Enterprise subscription
Client ID and Client Secret from Tallyfy
A registered redirect URI for your application
Basic understanding of OAuth 2.0 authorization flows

Standard OAuth Flow Implementation

Step 1: Redirect Users to Tallyfy Authorization Page

Direct your users to Tallyfy’s authorization endpoint:

https://account.tallyfy.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=token&redirect_uri=YOUR_REDIRECT_URL

Replace:

YOUR_CLIENT_ID with your application’s client ID
YOUR_REDIRECT_URL with your application’s registered redirect URI

Users will see Tallyfy’s login page where they can authenticate using their Tallyfy credentials.

Step 2: Handle the Redirect with Access Token

After successful authentication, Tallyfy will redirect the user back to your specified redirect URI with the access token in the URL fragment:

YOUR_REDIRECT_URL?access_token=ACCESS_TOKEN&token_type=Bearer&expires_in=EXPIRES_IN_SECONDS

Your application should:

Extract the access_token from the URL
Store it securely
Use it for subsequent API requests

Step 3: Make API Requests with the Access Token

Use the access token in the Authorization header for all API requests:

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
X-Tallyfy-Client: APIClient

Example Implementation

Example Authorization URL

https://account.tallyfy.com/oauth/authorize?client_id=9999&response_type=token&redirect_uri=https://yourapp.com/auth/callback

Example Redirect with Access Token

https://yourapp.com/auth/callback?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&token_type=Bearer&expires_in=840

Handling Multi-Organization Users

A user in Tallyfy can belong to multiple organizations. After authentication, the access token is associated with the organization the user is currently logged into. If your application needs to work with multiple organizations for a user:

Store the organization context along with the access token
Consider implementing organization selection in your application
For users in multiple organizations, you may need to handle organization-specific authentication flows

Security Best Practices

Always use HTTPS for all OAuth-related communication
Implement PKCE (Proof Key for Code Exchange) for added security
Store access tokens securely, preferably encrypted
Implement token expiration handling
Never expose your Client Secret in client-side code
Validate all redirect URIs against expected patterns
Implement state parameter to prevent CSRF attacks

Troubleshooting

Issue	Possible Cause	Solution
Authorization fails	Invalid client ID	Verify your client ID
Redirect fails	Mismatched redirect URI	Ensure the redirect URI matches exactly with the registered one
Token doesn’t work	Token expired	Check expiration time and request a new token
Organization context issues	User belongs to multiple organizations	Clarify organization context during authentication

For any issues with the OAuth implementation, contact Tallyfy Support with detailed information about the error and your implementation.

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

The guide outlines the integration process between third-party applications and Tallyfy API using client credentials flow to enable programmatic user provisioning and API request handling through application-level and user-specific access tokens.

Integrations > Open API

The Tallyfy REST API enables programmatic access to platform functionality through user-based or application authentication with features for process management task operations user administration template management data access and file operations.