# Social accounts (/docs/api/reference/social-accounts)



The social-accounts API is how Layers stores and refreshes the credentials your end-customers grant on TikTok and Instagram. Once a social account is connected to a project, its `socialAccountId` is what you pass as a target on every scheduling, metrics, and revocation call — the same opaque ID regardless of whether the account was authorized via OAuth or provisioned by Layers as a leased account.

The endpoints in this section cover the full lifecycle: mint an authorize URL, poll for completion, list connected accounts, refresh expired tokens, and disconnect. The OAuth handshake is the most involved — if you haven't wired one yet, **start with the quickstart** below; it walks through the full server glue end-to-end with TypeScript and Python samples.

<Callout type="info">
  **Start here:** Connect your first social account — a 15-minute walkthrough from "Connect" button to a live `socialAccountId`.
</Callout>

For background on how Layers represents OAuth-connected and leased accounts in one shape, see [Social accounts concepts](/docs/api/concepts/social-accounts).

## In this section [#in-this-section]

<Cards>
  <Card title="POST oauth-url" href="/docs/api/reference/social-accounts/oauth-url" description="Mint an authorize URL with an opaque state token. Strict returnUrl allowlist." />

  <Card title="GET oauth-status" href="/docs/api/reference/social-accounts/oauth-status" description="Poll until the state token flips to completed or failed. Returns the new socialAccountId." />

  <Card title="GET list" href="/docs/api/reference/social-accounts/list-social-accounts" description="Every connected and leased account on a project, with status." />

  <Card title="POST reauth-url" href="/docs/api/reference/social-accounts/reauth-url" description="Reconnect when a token expires — preserves the socialAccountId." />

  <Card title="GET health" href="/docs/api/reference/social-accounts/health" description="Per-account token + provisioning state for monitoring." />

  <Card title="DELETE revoke" href="/docs/api/reference/social-accounts/revoke-social-account" description="Disconnect an account. Cancels queued posts on it in one transaction." />
</Cards>