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

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.

Integrations > Open API

Tallyfy’s REST API gives developers full programmatic access to the same platform features that power its web app — including process management and task operations and template control and data export — with three authentication methods and standard JSON responses and required headers for every request.

Open Api > OAuth authorization flow for third-party applications

Tallyfy’s OAuth 2.0 implicit grant flow lets third-party apps authenticate users by redirecting them to Tallyfy’s login page and receiving a 6-month access token back in the URL fragment so the app never handles user credentials directly.

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.

Footnotes

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

Was this helpful?

YesNo