Skip to content
Tallyfy

OAuth authorization flow for third-party applications

OAuth implicit grant flow for third-party apps

Section titled “OAuth implicit grant flow for third-party apps”

Tallyfy uses the OAuth 2.0 implicit grant1 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

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

How the flow works

Section titled “How the flow works”

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

OAuth 2.0 Implicit Flow

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
  • You must include the X-Tallyfy-Client header in all API calls after authentication

Step 1 - redirect users to Tallyfy’s authorization page

Section titled “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 need 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

Section titled “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

Step 3 - make API requests with the access token

Section titled “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

Example implementation

Section titled “Example implementation”

Example authorization URL

Section titled “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

Section titled “Example redirect with access token”
https://yourapp.com/auth/callback#access_token=eyJhbGciOiJSUzI1NiIs...&token_type=Bearer&expires_in=15778800

Handling multi-organization users

Section titled “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. 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

Section titled “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

Section titled “Troubleshooting”
IssuePossible causeSolution
Authorization failsInvalid client IDVerify your client ID with Tallyfy Support
Redirect failsMismatched redirect URIThe redirect URI must match exactly what’s registered
Token doesn’t workToken expired or user email unverifiedCheck expiration and ensure the user has verified their email
Organization context issuesUser belongs to multiple organizationsClarify organization context during authentication

If you run into issues with your OAuth implementation, contact Tallyfy Support with details about the error and your setup.

Section titled “Related articles”

Footnotes

Section titled “Footnotes”

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

Get in touch
About Tallyfy