Skip to content
Tallyfy

Third-party application API access

How third-party apps access Tallyfy’s API

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

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

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

OAuth client credentials flow

Section titled “OAuth client credentials flow”

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

OAuth client credentials flow

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

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

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

Step 3 - Provision users

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

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

Step 5 - Make API calls as that user

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

Security tips

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

Section titled “Troubleshooting”
ErrorCauseFix
401 UnauthorizedBad client credentialsDouble-check your client ID and secret
403 ForbiddenToken doesn’t match the organizationVerify the client is linked to the correct org
404 Not FoundUser doesn’t existCheck the email and organization ID
422 UnprocessableUser not in your orgThe email exists but isn’t part of your organization
429 Too Many RequestsRate limit hitWait the seconds given in the Retry-After header, then retry

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

Section titled “Related articles”

Integrations > Open API

Tallyfy’s REST API gives developers full programmatic access to the same platform features that…

Footnotes

Section titled “Footnotes”

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

Get in touch
About Tallyfy