Hubstaff - Setup Guide

Overview

The Hubstaff source syncs Hubstaff organization, member, activity, daily activity, and time off request data into Daspire.

Prerequisites

• A Hubstaff account that can authorize API access for each organization you want to sync.

Authentication

1. In Daspire, click Authenticate with Hubstaff.
2. Sign in to Hubstaff and approve the requested OAuth access.
3. After authorization succeeds, choose one or more organizations from the list Daspire loads from Hubstaff.
4. Daspire stores the OAuth tokens securely. You do not need to enter a Hubstaff OAuth client secret or refresh token manually.

The connector uses Hubstaff OAuth 2.0 / OIDC authorization code flow and the Hubstaff token endpoint:

https://account.hubstaff.com/access_tokens

Refresh-token behavior differs between the legacy and Native runtimes. For an existing saved access token, the guarded Native revision rejects an expired, near-expiry or malformed token before making a refresh request. The platform must durably capture and publish the next credential generation; repeating a sync cannot repair that material. Verify deployment of this revision before relying on this protection. First authentication without a cached access token remains a separate path: if Hubstaff returns a rotated refresh token, the connector fails closed and does not persist that replacement through the product credential service. A successful credential check alone therefore does not establish durable refresh-token handling. Complete the product credential update before resuming a connection that requires rotation.

For an existing Native source, an authenticated source update accepts your owned OAuth credential handle only for the same account and original organizations. It saves the access and refresh tokens together and preserves replication settings, checkpoints and each connection's schedule; it does not start a sync. Save source-name or organization changes separately. If the response reports SOURCE_REAUTH_RECONCILE_REQUIRED or SOURCE_REAUTH_INTERRUPTED, contact support before retrying: a partial scheduling update must be reconciled first. This product-save capability does not yet provide autonomous Native token rotation.

Organizations

Daspire normally fills this field from the organizations returned by Hubstaff after OAuth. Select the organization or organizations you want this source to sync.

Manual entry is only a fallback for existing or migrated configurations. To find a Hubstaff Organization ID manually:

1. Log in to Hubstaff.
2. Open the organization dashboard.
3. Copy the numeric organization ID from the URL, for example:

https://app.hubstaff.com/dashboard/12345/team

For one organization, use 12345. For multiple organizations, use a comma-separated list such as 12345,67890.

Configuration

Field	Required	Notes
Hubstaff Organizations	Yes	Select one or more Hubstaff organizations after OAuth. Existing/manual configs can use one ID or a comma-separated list.
Start Date	Yes	UTC date or date-time used by activities and daily_activities incremental reads.
Recent Activity Refresh Window (Days)	No	Number of recent days to re-read on each ongoing incremental sync. Defaults to 3 days.
End Date	No	Optional bounded end date for backfills. Leave empty to sync through now.
Page Limit	No	Advanced setting for Hubstaff list pagination.

Activity Refresh Window

Hubstaff can update or backfill time and activity records after their original activity date. To capture those late changes, Daspire re-reads the most recent activity window on ongoing incremental syncs.

• On the first sync, activities and daily_activities start from Start Date.
• On later incremental syncs without End Date, the connector starts from the saved cursor minus Recent Activity Refresh Window (Days), capped at Start Date, and syncs through now.
• When End Date is set, the connector keeps the sync bounded to the fixed historical range instead of rolling forward to now.

Native Hubstaff reads preserve acknowledged per-stream cursors when converting supported legacy stream-state messages or legacy per-stream maps into Native checkpoints. Unknown, malformed, conflicting or namespace-specific nonempty state fails with oci_source_state_invalid; it must not silently restart from Start Date. This compatibility is specific to Hubstaff, not a global conversion for other connectors. Do not reset state or resubmit already committed data to work around a state-format error.

The activity streams intentionally emit records from the refresh window again. Use a destination sync mode that can update existing records by primary key when you need corrected Hubstaff values to replace older copies.

Supported Streams

Stream	Sync Modes	Primary Key	Cursor
organizations	Full refresh	id	None
members	Full refresh	organization_id, user_id	None
activities	Full refresh, incremental	organization_id, id	time_slot
daily_activities	Full refresh, incremental	organization_id, id	date
time_off_requests	Full refresh	organization_id, id	None

The activity streams request Hubstaff side-loaded users, projects, and tasks where supported by the API and include those arrays on emitted records.

Limits

• activities is sliced into Hubstaff time_slot[start] / time_slot[stop] requests no longer than 7 days.
• daily_activities is sliced into Hubstaff date[start] / date[stop] requests no longer than 31 days.
• Hubstaff rate limits may return HTTP 429. Native GET retries honor Retry-After regardless of header capitalization, including delay-seconds and HTTP-date values. An hourly quota wait keeps the same page and current invocation; it does not refresh OAuth, restart the sync, or replay already emitted pages. The attempt budget and overall execution deadline still apply.
• Interrupted or malformed page responses use the same bounded retry budget for GET requests, before any records from that page are emitted. This does not add OAuth refresh POST retries or autonomous token rotation.
• Hubstaff GET 5xx and network timeouts use bounded backoff. A token refresh POST is not an idempotent page request: do not repeat an uncertain exchange or assume that a missing response means the refresh token was not consumed. The guarded connector revision disables such POST retries; deployment and durable product credential publication must be verified separately.
• A zero-second or elapsed Retry-After still waits at least one second, preventing an instant retry loop at a rounded quota-reset boundary.

Troubleshooting

Error	Action
Authentication failed or HTTP 401	Re-authenticate the Hubstaff source in Daspire.
HTTP 403 or missing organization access	Re-authorize with a Hubstaff user that can access the selected organization.
Error 1010, browser signature blocked	This is a provider-edge client compatibility rejection, not proof that OAuth access was revoked. Use a supported connector release with the explicit Daspire API client identity; check provider-edge policy if it persists.
credential_rotation_required	Contact support to reconcile the original refresh response and the product credential binding. This code alone does not prove that customer OAuth authorization is invalid; do not repeatedly trigger sync.
Organization ID not found	Re-authorize and select the organization again. For manual configs, re-check the ID from the Hubstaff dashboard URL.
Rate limit exceeded	Wait for the Hubstaff rate limit window to reset, then retry.
Empty activity results	Confirm the Start Date / End Date range and that Hubstaff has activity data in that period.

Additional Resources

• Hubstaff API Documentation
• Hubstaff Authentication Guide