OAuth authorization flow for third-party applications

OAuth implicit grant flow for third-party apps

Tallyfy uses the OAuth 2.0 implicit grant¹ flow for third-party application authentication. Your users log in directly on Tallyfy’s domain, and an access token comes back in the URL fragment - your app never touches their credentials.

Requirements

• Paid Tallyfy Pro or Enterprise subscription
• Client ID from Tallyfy (contact support)
• A registered redirect URI for your application

Paid feature

The OAuth authorization flow is only available to paid organizations. Contact Tallyfy Support to get a Client ID for your application.

How the flow works

Here’s the complete OAuth 2.0 implicit flow for authenticating third-party applications with Tallyfy.

Diagram description: OAuth 2.0 implicit flow showing the 11-step authentication process where users log in directly with Tallyfy and receive an access token via URL fragment, which the third-party app extracts for Bearer-authenticated API requests.

What to notice:

• The access token is returned in the URL fragment (after #) - fragments aren’t sent to servers, which adds a layer of protection
• Authentication happens entirely on Tallyfy’s domain, so your app never sees user credentials
• The X-Tallyfy-Client header is required for all API calls after authentication

Step 1 - Redirect users to Tallyfy’s authorization page

Direct your users to the Tallyfy 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 and YOUR_REDIRECT_URL with your registered redirect URI. Users must have a verified email to proceed - they’ll see Tallyfy’s login page where they authenticate with their own credentials.

Step 2 - Handle the redirect with the access token

After successful authentication, Tallyfy redirects back to your redirect URI with the access token in the URL fragment (after #, not ?):

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

Your application should:

1. Extract the access_token from the URL fragment using client-side JavaScript
2. Store it securely
3. Use it for subsequent API requests

Token lifetime

Implicit grant tokens are valid for 6 months. Plan your token refresh strategy accordingly.

Step 3 - Make API requests with the access token

Include the access token in the Authorization header for all Tallyfy API requests:

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

Required headers

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

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=eyJhbGciOiJSUzI1NiIs...&token_type=Bearer&expires_in=15778800

Handling multi-organization users

A Tallyfy user can belong to multiple organizations. After authentication, the access token is tied to whichever organization the user is logged into at the time. If your app needs to work across multiple Tallyfy organizations:

1. Store the organization context alongside the access token
2. Consider adding organization selection in your application
3. You may need separate authentication flows per organization

Security best practices

• Always use HTTPS for all OAuth-related communication
• Store access tokens securely and encrypted at rest
• Monitor token expiration and prompt re-authentication before tokens expire
• Validate all redirect URIs against expected patterns

Troubleshooting

Issue	Possible cause	Solution
Authorization fails	Invalid client ID	Verify your client ID with Tallyfy Support
Redirect fails	Mismatched redirect URI	The redirect URI must match exactly what’s registered
Token doesn’t work	Token expired or user email unverified	Check expiration and ensure the user has verified their email
Organization context issues	User belongs to multiple organizations	Clarify organization context during authentication

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

Related articles

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

Third-party apps can access Tallyfy’s API through an OAuth 2.0 client credentials flow where the app first obtains an application-level token using a client ID and secret and then exchanges it for user-specific tokens to perform workflow actions on behalf of individual users within a paid organization.

Open Api > API integration guide

Tallyfy’s REST API enables you to connect workflow features to external systems using OAuth 2.0 authentication with required Bearer tokens and X-Tallyfy-Client headers while mapping API terminology like Checklists and Runs to their UI equivalents of Templates and Processes and handling token refresh and multi-organization context for reliable integrations.

Authentication > Use the client credentials flow

Tallyfy’s OAuth 2.0 client credentials flow lets backend services and third-party apps authenticate without user login by obtaining a Client ID and Client Secret from Tallyfy Support and then exchanging them for application-level tokens (valid 7 days) or user-specific tokens (valid 3 months) to call the API on behalf of an organization or individual users.

Authentication > Get & use a personal access token

Tallyfy’s API allows quick authentication using a personal access token found in Settings > Integrations > REST API which must be sent as a Bearer token alongside Accept and X-Tallyfy-Client headers on every request and expires after six months or immediately upon logging out of the web interface.

Footnotes

1. A simplified OAuth flow where the access token is returned directly in the redirect URL fragment - no intermediate authorization code exchange needed ↩

Was this helpful?

YesNo