Skip to content
Developers

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 on your redirect URL, after ?. Your app never touches their credentials.

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

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

OAuth 2.0 Implicit Flow1. User startslogin in your app2. App sends user to/oauth/authorize3. User logs in andapproves your app4. Tallyfy redirects backwith token after ?5. App reads tokenfrom the query string6. App calls the APIwith Bearer token Token expiresafter 6 months

Diagram description: OAuth 2.0 implicit flow showing the 6-step authentication process where users log in directly with Tallyfy and receive an access token in the redirect URL’s query string, which the third-party app reads for Bearer-authenticated API requests. The dashed arrow shows the login starting again when the token expires after 6 months.

What to notice:

  • The access token comes back in the query string (after ?), so it reaches your server and its logs. Take it out of the address bar once you’ve read it, and keep it out of your logs
  • 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. Tallyfy then asks them to approve your app’s access, unless they already hold a valid token from it.

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 query string (after ?, not #):

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

Your application should:

  1. Read access_token from the query string: on your server from the request, or in the browser from location.search (not location.hash)
  2. Take it out of the address bar, for example with history.replaceState, and keep it out of your logs
  3. Store it securely
  4. 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
https://account.tallyfy.com/oauth/authorize?client_id=9999&response_type=token&redirect_uri=https://yourapp.com/auth/callback
https://yourapp.com/auth/callback?access_token=eyJhbGciOiJSUzI1NiIs...&token_type=Bearer&expires_in=15778800

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
  • 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
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.

  1. A simplified OAuth flow where the access token is returned directly on the redirect URL, with no intermediate authorization code exchange needed ↩