API usage as a third-party application instead of a user

How third-party apps access Tallyfy’s API

Your application can make Tallyfy API calls on behalf of users through the OAuth 2.0 client credentials flow¹. You’ll get an app-level token first, then exchange it for user-specific tokens that let you act as individual users.

When to use this pattern

• Embed Tallyfy workflow features inside your own software
• Automate user provisioning for clients or employees
• Run process management actions without users logging into Tallyfy directly

What you’ll need

• A paid Tallyfy Pro or Enterprise subscription
• Client credentials (client ID and secret) from Tallyfy Support
• Familiarity with OAuth 2.0 client credentials flow

Paid feature

Client credentials access is only available to paid organizations - not during free trials. Contact Tallyfy Support to get set up.

OAuth client credentials flow

Here’s the full authentication flow for third-party applications.

What to notice:

• Your app authenticates itself first to get an app-level token
• Both user provisioning and user token generation need that app-level token - this creates a chain of trust
• App tokens manage users. User tokens perform workflow actions. They’re distinct on purpose.

Step 1 - Get client credentials

1. Contact Tallyfy Support and describe your integration use case
2. Tallyfy provisions a client ID and secret tied to your organization
3. Store these credentials securely (environment variables, secrets manager, etc.)

Step 2 - Get an application access token

Send a POST request to get your app-level token.

POST https://account.tallyfy.com/oauth/token

Request body (form-encoded):

grant_type=client_credentials
client_id=12345
client_secret=hTWzy5rpYXcBn8K4J9PqEs2V...
scope=*

Headers:

Content-Type: application/x-www-form-urlencoded

Response:

{
    "token_type": "Bearer",
    "expires_in": 604800,
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Token expiration

App tokens last 7 days (604,800 seconds). Request a fresh token before the current one expires - there’s no separate refresh endpoint.

Step 3 - Provision users

Create users in your Tallyfy organization using the app token.

POST https://go.tallyfy.com/api/applications/{orgID}/users

Headers:

Authorization: Bearer {your_app_access_token}
Content-Type: application/json
X-Tallyfy-Client: APIClient

Request body:

{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@yourcompany.com",
    "role": "standard",
    "timezone": "America/Chicago"
}

Available roles:

• admin - full organization administration access
• standard - can create and manage processes
• light - can only complete assigned tasks

Both first_name and last_name are required (max 32 characters each). The role and timezone fields are optional.

Response:

{
    "data": {
        "id": 12345,
        "email": "john.smith@yourcompany.com",
        "first_name": "John",
        "last_name": "Smith",
        "role": "standard",
        "created_at": "2024-01-15T14:22:10.000Z"
    }
}

Step 4 - Generate user-specific tokens

To act as a specific user, request a token for their email address.

POST https://go.tallyfy.com/api/applications/{orgID}/users/{email}/token

Headers:

Authorization: Bearer {your_app_access_token}
Content-Type: application/json
X-Tallyfy-Client: APIClient

No request body needed - the email goes in the URL path. The user must already exist in your organization.

Response:

{
    "token_type": "Bearer",
    "expires_in": 7776000,
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

User token validity

User tokens last 3 months (7,776,000 seconds). Build your refresh logic around this timeline.

Step 5 - Make API calls as that user

Use the user-specific token for any Tallyfy API call. It works exactly as if the user made the request themselves.

GET https://go.tallyfy.com/api/organizations/{orgID}/me/tasks

Headers:

Authorization: Bearer {user_specific_access_token}
Content-Type: application/json
X-Tallyfy-Client: APIClient

Required header

Always include X-Tallyfy-Client: APIClient in every API call. Requests without it may not work correctly.

Security tips

• Keep client credentials in encrypted storage or a secrets manager
• Control which parts of your app can access user tokens
• Confirm user emails belong to your organization before requesting tokens
• Handle token expiration gracefully - refresh before they expire, not after

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Bad client credentials	Double-check your client ID and secret
403 Forbidden	Token doesn’t match the organization	Verify the client is linked to the correct org
404 Not Found	User doesn’t exist	Check the email and organization ID
422 Unprocessable	User not in your org	The email exists but isn’t part of your organization
429 Too Many Requests	Rate limit hit	Add request throttling and retry logic

Contact Tallyfy Support if you’re stuck - include your error messages and the endpoint you’re calling.

Related articles

Authentication > Use the client credentials flow

The OAuth 2.0 client credentials flow lets server-side apps authenticate with Tallyfy’s API using a client ID and secret to get application-level tokens (valid 7 days) and optional user-specific tokens (valid 3 months) for acting as individual users.

Integrations > Open API

Tallyfy’s REST API gives developers full programmatic access to every core platform feature—including process management and task operations and user control and data export—using standard JSON responses and three authentication methods (user tokens and application tokens and OAuth) with required headers sent to a single production endpoint.

Open Api > OAuth authorization flow for third-party applications

Tallyfy supports the OAuth 2.0 implicit grant flow so third-party apps can authenticate users through a redirect-based process that returns access tokens without exposing user credentials to your application.

Open Api > API integration guide

The Tallyfy REST API enables workflow automation through two authentication methods (user-based tokens obtained from Settings or application-based OAuth credentials) requiring specific headers and proper token management while supporting multi-organization contexts and webhook integrations with standardized date formats.

Footnotes

1. OAuth 2.0 is an industry-standard protocol for delegated authorization without sharing passwords ↩

Was this helpful?

YesNo