Authentication > Use the client credentials flow
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.
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.
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-Clientheader 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_URLReplace 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_SECONDSYour application should:
- Read
access_tokenfrom the query string: on your server from the request, or in the browser fromlocation.search(notlocation.hash) - Take it out of the address bar, for example with
history.replaceState, and keep it out of your logs - Store it securely
- 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_TOKENContent-Type: application/jsonX-Tallyfy-Client: APIClientExample 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/callbackExample redirect with access token
Section titled “Example redirect with access token”https://yourapp.com/auth/callback?access_token=eyJhbGciOiJSUzI1NiIs...&token_type=Bearer&expires_in=15778800Handling 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:
- Store the organization context alongside the access token
- Consider adding organization selection in your application
- 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”| 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 |
If you run into issues with your OAuth implementation, contact Tallyfy Support with details about the error and your setup.
Related articles
Section titled “Related articles”Open Api > Third-party application API access
Code Samples > Authentication methods
Authentication > Get & use a personal access token
Footnotes
Section titled “Footnotes”-
A simplified OAuth flow where the access token is returned directly on the redirect URL, with no intermediate authorization code exchange needed ↩