Skip to content

Use the Client Credentials Flow

Overview

The OAuth 2.0 Client Credentials flow is designed for machine-to-machine authentication, typically used by third-party applications or backend services that need to interact with the Tallyfy API independently or on behalf of users within an organization.

This method requires you to first obtain a Client ID and Client Secret from Tallyfy Support.

Use Cases

This integration pattern is ideal for:

  • Embedding Tallyfy functionality within your own software.
  • Providing seamless workflow capabilities to your users without them needing separate Tallyfy logins visible in your app.
  • Automating process management or user provisioning programmatically.
  • System-level integrations (e.g., reporting, data synchronization).

Steps

1. Request Client Credentials

  • Contact Tallyfy Support to request client credentials (Client ID and Client Secret).
  • Explain your integration needs.
  • Tallyfy will provide the credentials for your organization. Store them securely.

2. Obtain an Application Access Token

Your application first needs its own access token to perform actions like user provisioning or getting user-specific tokens.

  • Endpoint: POST /oauth/token
  • Base URL: https://go.tallyfy.com/api (The primary API base URL).
  • OAuth Endpoint: https://go.tallyfy.com/api/oauth/token (Used specifically for getting the access token).
  • Request Body (form-data):
    • grant_type: client_credentials
    • client_id: Your Application’s Client ID
    • client_secret: Your Application’s Client Secret
    • scope: * (or specific scopes if provided by Tallyfy)

Example (Conceptual cURL):

Terminal window
curl -X POST https://go.tallyfy.com/api/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d client_id=YOUR_CLIENT_ID \
     -d client_secret=YOUR_CLIENT_SECRET \
     -d scope='*'

Response:

{
    "token_type": "Bearer",
    "expires_in": 3600, // Typically 1 hour
    "access_token": "APP_LEVEL_ACCESS_TOKEN_EXAMPLE..."
}

3. (Optional) Provision Users Programmatically

Using the application-level token obtained in Step 2, you can manage users. Refer to the Members code samples section for specific examples once available. The general endpoint mentioned previously was POST /api/applications/{orgID}/users, but check the current Swagger definition for the correct endpoint, likely under /organizations/{org}/users/invite or similar, using the application token as the Bearer token.

4. (Optional) Generate User-Specific Access Tokens

To act as a specific user, request a user-specific token using the application token.

  • Endpoint: POST /api/applications/{orgID}/users/{email}/token (Verify this endpoint with Tallyfy Support or Swagger spec; it might differ from standard OAuth patterns).
  • Base URL: Check with Tallyfy Support if this specific endpoint uses go.tallyfy.com or api.tallyfy.com.
  • Headers:
    • Authorization: Bearer {your_app_access_token} (From Step 2)
    • Content-Type: application/json
    • X-Tallyfy-Client: APIClient

Response:

{
    "token_type": "Bearer",
    "expires_in": 3600, // User token lifetime
    "access_token": "USER_SPECIFIC_ACCESS_TOKEN_EXAMPLE..."
}

5. Make API Requests (as Application or User)

Use the appropriate token (APP_LEVEL_ACCESS_TOKEN or USER_SPECIFIC_ACCESS_TOKEN) in the Authorization: Bearer {token} header for subsequent API calls, along with the standard Accept and X-Tallyfy-Client headers.

Example: Get tasks for a specific user (using user-specific token)

  • Endpoint: GET /organizations/{orgID}/me/tasks
  • Base URL: https://go.tallyfy.com/api
  • Resource Path: e.g., /organizations/{org_id}/users
  • Full URL: https://go.tallyfy.com/api/organizations/{org_id}/users
  • Headers:
    • Authorization: Bearer {user_specific_access_token}
    • Accept: application/json
    • X-Tallyfy-Client: APIClient

Code examples for making the requests themselves are similar to those shown in the Personal Access Token guide, just substitute the correct token.

Security Considerations

  • Store client credentials securely (e.g., encrypted secrets management).
  • Protect both application-level and user-specific tokens.
  • Rotate secrets periodically.
  • Use HTTPS for all communications.
  • Implement robust token expiration and refresh logic.
Get in touch
About Tallyfy