Authentication setup for Postman

Tallyfy’s API uses OAuth 2.0 with the password grant type. Most endpoints need user context, so you’ll configure Postman with your credentials, set up the required headers, and store tokens automatically.

What you need to know first

Here’s what trips people up:

• Password grant is required — most endpoints need user context, not just application-level access
• The X-Tallyfy-Client header is required — include it on every request
• Access tokens last 6 months — refresh tokens last 12 months
• Client credentials grant is limited — those tokens only last 7 days and can’t access user-scoped endpoints

Setting up authentication step by step

1. Get your credentials from Tallyfy

   Go to Settings > Integrations > REST API. You’ll need:

   • Client ID (a numeric value)
   • Client Secret
   • Organization ID
   • Your Tallyfy username and password

2. Create your Postman environment

   Click Environments > Create Environment and add these variables:

   TALLYFY_CLIENT_ID = [your client id]
   TALLYFY_CLIENT_SECRET = [your client secret]
   TALLYFY_ORG_ID = [your org id]
   TALLYFY_USERNAME = your@email.com
   TALLYFY_PASSWORD = [your password]
   TALLYFY_BASE_URL = https://go.tallyfy.com/api

3. Create the token request

   Create a new POST request:

   POST {{TALLYFY_BASE_URL}}/oauth/token
   
   Body (x-www-form-urlencoded):
   grant_type = password
   username = {{TALLYFY_USERNAME}}
   password = {{TALLYFY_PASSWORD}}
   client_id = {{TALLYFY_CLIENT_ID}}
   client_secret = {{TALLYFY_CLIENT_SECRET}}

4. Store tokens automatically

   Add this to your token request’s Tests tab:

   pm.test("Token response is valid", () => {
       pm.expect(pm.response.code).to.equal(200);
       const response = pm.response.json();
       pm.expect(response).to.have.property('access_token');
       pm.expect(response).to.have.property('expires_in');
   });
   
   if (pm.response.code === 200) {
       const response = pm.response.json();
   
       pm.environment.set("TALLYFY_ACCESS_TOKEN", response.access_token);
       pm.environment.set("TALLYFY_REFRESH_TOKEN", response.refresh_token);
   
       const expiryTime = new Date().getTime() + (response.expires_in * 1000);
       pm.environment.set("TALLYFY_TOKEN_EXPIRY", expiryTime);
       pm.environment.set("TALLYFY_TOKEN_TYPE", response.token_type || "Bearer");
   
       console.log(`Token acquired. Expires in ${Math.round(response.expires_in/3600)} hours`);
   }

Authentication flow visualization

This diagram shows the OAuth lifecycle — initial token grant, API usage, and token refresh.

What to notice:

• Steps 1-3 — the password grant requires all four parameters (username, password, client_id, client_secret)
• Step 5 — every API call needs both the Bearer token and the X-Tallyfy-Client header
• Steps 9-12 — refresh happens before expiry using the stored refresh token

The required headers

Every API request needs two headers. Add them to your collection’s pre-request script so you don’t have to set them manually each time:

pm.request.headers.add({
    key: 'X-Tallyfy-Client',
    value: 'APIClient'
});

const token = pm.environment.get("TALLYFY_ACCESS_TOKEN");
if (token) {
    pm.request.headers.add({
        key: 'Authorization',
        value: `Bearer ${token}`
    });
}

Token refresh

Access tokens last 6 months and refresh tokens last 12 months. You probably won’t hit expiry during a testing session, but here’s a pre-request script that handles refresh automatically:

const tokenExpiry = pm.environment.get("TALLYFY_TOKEN_EXPIRY");
const now = new Date().getTime();

if (!tokenExpiry || now >= tokenExpiry - 300000) {
    const refreshToken = pm.environment.get("TALLYFY_REFRESH_TOKEN");

    if (refreshToken) {
        pm.sendRequest({
            url: pm.environment.get("TALLYFY_BASE_URL") + "/oauth/token",
            method: 'POST',
            header: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: {
                mode: 'urlencoded',
                urlencoded: [
                    {key: 'grant_type', value: 'refresh_token'},
                    {key: 'refresh_token', value: refreshToken},
                    {key: 'client_id', value: pm.environment.get("TALLYFY_CLIENT_ID")},
                    {key: 'client_secret', value: pm.environment.get("TALLYFY_CLIENT_SECRET")}
                ]
            }
        }, (err, res) => {
            if (!err && res.code === 200) {
                const response = res.json();
                pm.environment.set("TALLYFY_ACCESS_TOKEN", response.access_token);
                pm.environment.set("TALLYFY_REFRESH_TOKEN", response.refresh_token);
                pm.environment.set("TALLYFY_TOKEN_EXPIRY",
                    now + (response.expires_in * 1000));
                console.log("Token refreshed successfully");
            } else {
                console.error("Token refresh failed - request a new token manually");
            }
        });
    }
}

Grant types compared

Grant type	What it does	When to use
password	Full user context — access all endpoints	API testing in Postman
client_credentials	Application-only access (7-day tokens)	Automated system integrations
refresh_token	Gets a new access token	When your current token expires

Use password grant for Postman testing. Client credentials won’t give you access to user-scoped endpoints like templates, processes, or tasks.

Security tips

• Mark sensitive variables as secret in Postman so they’re masked
• Use the initial/current value distinction — initial values sync with your team, current values stay local
• Don’t commit exported environments to version control
• When sharing collections, export them without the environment and document which variables teammates need to create

Common errors and fixes

401 Unauthenticated:

1. Missing X-Tallyfy-Client: APIClient header
2. Token has expired — request a new one or check your refresh script
3. Using client_credentials grant for a user-scoped endpoint — switch to password
4. Malformed Authorization header — it should be Bearer [token] with exactly one space

400 Bad Request on the token endpoint:

• Body must be x-www-form-urlencoded, not JSON
• All parameters (grant_type, username, password, client_id, client_secret) must be present

Invalid client:

• Double-check your Client ID and Client Secret
• Make sure you’re using the right Postman environment

Testing your setup

Send this request to confirm everything works:

GET {{TALLYFY_BASE_URL}}/me

Headers:
Authorization: Bearer {{TALLYFY_ACCESS_TOKEN}}
X-Tallyfy-Client: APIClient
Accept: application/json

If you get your user details back, you’re all set.

Next steps

With authentication working, you can:

• Work with templates and processes
• Automate task operations

Related articles

Postman > Troubleshooting common issues

Most Tallyfy API failures in Postman stem from three issues: a missing X-Tallyfy-Client header and wrong grant type or expired tokens and this guide covers how to diagnose and fix every common error including 401 authentication problems and 404 path mistakes and 422 validation failures and rate limiting and file upload issues along with ready-to-use debugging scripts for your Postman collection.

Api Clients > Getting started with Postman API testing

Postman serves as a code-free testing environment for Tallyfy’s REST API where you authenticate using the password grant type and then explore endpoints for templates (called checklists) and processes (called runs) and tasks across your organization.

Code Samples > Authentication methods

Tallyfy API authentication requires either a personal access token (from Settings lasting 6 months) or a client credentials OAuth flow (using client ID and secret for 7-day tokens) and every request must include Authorization Bearer token along with Accept and X-Tallyfy-Client headers to work properly.

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.

Was this helpful?

YesNo