TimeToPostDocs
Sign in
Documentation menu

Integrations

TimeToPost publishes through each platform’s official API, authorized by you via OAuth. No passwords are stored — you grant access on the platform’s own consent screen, and you can revoke it there or in TimeToPost at any time. This page covers the connect flow for Instagram, TikTok and X, and what to do when a connection expires.

How connecting works

Every platform follows the same pattern: in Dashboard → Integrations, click Connect next to a platform. TimeToPost requests an authorization URL from the backend (GET /api/integrations/:provider/auth) and opens it in a popup. You log in on the platform, approve the permissions, and the platform redirects back to TimeToPost’s callback, which stores the access token and account details. The popup closes and the account appears in your list with status connected. You can connect multiple accounts per platform and group them into collections (handy for agencies).

Instagram

  • Account type: a Professional account (Business or Creator) is required — Meta’s API does not allow publishing to personal Instagram accounts.
  • What you grant: permission to publish media and read basic profile and engagement data, which powers the best-time-to-post analytics.
  • Content rules: Instagram posts must include at least one image or video; caption-only posts are rejected by the platform.

TikTok

  • Account type: any TikTok account; you authorize with the account you want to post from.
  • What you grant: video upload/publish permission plus read access to video performance metrics.
  • Content rules: TikTok is video-first — schedule posts with a video attached. Upload media first (see media uploads) and reference it from the post.

X (Twitter)

  • Account type: any X account. In the API the provider is named twitter.
  • What you grant: permission to post on your behalf and read tweet metrics.
  • Content rules: text-only posts are fine; images and video are optional.

Connection statuses

Each connected account has a status: connected (healthy), expired (the platform token lapsed and needs re-authorization), error (the last operation failed — details are kept with the account), and disconnected (you removed it). Posts only publish through connected accounts.

Reconnecting when a token expires

Platform tokens have finite lifetimes — notably, long-lived Meta tokens last about 60 days, and TikTok tokens refresh on a shorter cycle. TimeToPost refreshes tokens proactively in the background, but a connection can still expire if, for example, you change your password on the platform or revoke the app there.

When that happens:

  1. The account’s status flips to expired on the Integrations page.
  2. The composer shows a reconnect prompt on that account instead of letting you target it silently — so you find out before a scheduled post fails, not after.
  3. Click Reconnect: it runs the same OAuth popup as the first connection. Your scheduled posts, groups, and analytics history are untouched — only the token is replaced.

If a post does fire while an account is expired, that account’s result fails and the post lands in FAILED or PARTIAL (multi-account) status. Reconnect, then republish.

For API users

List your connected accounts
curl https://timetopost.co/api/integrations \
  -H "Authorization: Bearer ttp_your_token_here"

# Each integration includes: id, provider, accountName, status, capabilities

Use the integration id values as accountIds when creating posts via the API, and check status before scheduling to catch expired connections early.

Previous← SchedulingNextAPI reference →