Skip to content
Tallyfy

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.

Diagram

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 typeWhat it doesWhen to use
passwordFull user context — access all endpointsAPI testing in Postman
client_credentialsApplication-only access (7-day tokens)Automated system integrations
refresh_tokenGets a new access tokenWhen 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:

Postman > Troubleshooting common issues

Fixing Postman errors with Tallyfy’s API requires checking the X-Tallyfy-Client header first then verifying the authentication grant type is password (not client_credentials) and ensuring tokens haven’t expired since these three issues cause most API failures.

Api Clients > Getting started with Postman API testing

Set up Postman with Tallyfy’s REST API to test workflow automation endpoints including OAuth authentication with the password grant type, required headers, and common operations like launching processes and completing tasks.

Code Samples > Authentication methods

Tallyfy’s API supports personal access tokens for quick user-level access and OAuth client credentials for server-to-server integrations, each requiring specific headers on every request.

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.
Get in touch
About Tallyfy