Skip to content
Tallyfy

Authentication setup for Postman

Tallyfy’s API uses OAuth 2.0 with the password grant type. You’ll give Postman your credentials, add the required headers, and store tokens automatically.

What you need to know first

Section titled “What you need to know first”

Most Tallyfy API endpoints act for a signed-in person, not just for an app. So Postman has to sign in as you. Four things catch people out:

  • You need the password grant. It signs Postman in as a user, and most endpoints need one.
  • Tokens last a long time. Access tokens last 6 months. Refresh tokens last 12 months.
  • The client credentials grant is limited. Its tokens only last 7 days, and they can’t reach user-scoped endpoints.
  • The X-Tallyfy-Client header is required. Include it on every request.

Setting up authentication step by step

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

Section titled “Authentication flow visualization”

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

Authentication flow visualizationPostmanClientTallyfy OAuthServerTallyfy API 1. Password grantrequest2. Validatecredentials3. Return tokens(access + refresh)4. Store tokensin environment5. API request withBearer + X-Tallyfy-Client6. Validate headersand token7. Return APIresponse8. Check tokenexpiry9. Refresh token(before expiry)10. New tokens11. Update storedtokens12. Continue APIcalls13. Success

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

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

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

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

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

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

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

Section titled “Next steps”

With authentication working, you can:

Section titled “Related articles”
Get in touch
About Tallyfy