# DELETE /v1/social-accounts/:socialAccountId (/docs/api/reference/social-accounts/revoke-social-account)



<Endpoint method="DELETE" path="/v1/social-accounts/:socialAccountId" auth="Bearer" scope="social:write" phase="1" />

Disconnect a social account. Layers drops the stored token, marks the account `disconnected` (with `disconnectedReason = "revoked_by_partner"`), and cancels every queued post targeting it. Already-published posts stay on the platform - we don't delete upstream content.

Use this when the end-customer asks to disconnect, or as part of offboarding a customer. For leased accounts, [`DELETE /v1/leased-accounts/:id`](/docs/api/reference/leased-accounts/release-leased-account) is the better endpoint - it releases the billing as well.

<Callout type="warn">
  Revoking cancels all queued scheduled posts on this account in a single transaction. The response's `canceledScheduledPosts` count is your audit trail. If that number surprises you, stop and re-check before moving on.
</Callout>

<Parameters
  title="Path"
  rows="[
  { name: 'socialAccountId', type: 'string', required: true, description: 'Account to revoke.' },
]"
/>

This endpoint takes no request body. The cancellation reason is recorded internally as `revoked_by_partner`.

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.layers.com/v1/social-accounts/sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e \
      -H "Authorization: Bearer lp_..."
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const result = await layers.social.revoke({
      socialAccountId: "sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e",
    });

    console.log(`Canceled ${result.canceledScheduledPosts} queued posts.`);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    result = layers.social.revoke(
        social_account_id="sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e",
    )
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="Revoked">
  ```json
  {
    "socialAccountId": "sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e",
    "status": "disconnected",
    "disconnectedReason": "revoked_by_partner",
    "canceledScheduledPosts": 4,
    "disconnectedAt": "2026-04-18T19:15:02Z"
  }
  ```
</Response>

## Errors [#errors]

See [Errors](/docs/api/operational/errors) for the canonical envelope and full code catalog. Endpoint-specific notes:

| Status | Code                   | When                                                                                                                                                                                                                      |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `VALIDATION`           | `socialAccountId` path param malformed (not a `sa_<uuid>` shape).                                                                                                                                                         |
| 401    | `UNAUTHENTICATED`      | Missing or invalid `Authorization` header.                                                                                                                                                                                |
| 403    | `FORBIDDEN_SCOPE`      | Key lacks `social:write`. `details.requiredScope` names the scope.                                                                                                                                                        |
| 404    | `NOT_FOUND`            | Account not in your organization, or already disconnected. Returned (not `403`) deliberately so the API doesn't leak cross-org existence.                                                                                 |
| 409    | `IDEMPOTENCY_CONFLICT` | Same `Idempotency-Key` was used earlier with a materially different request shape. DELETE is naturally idempotent; this surfaces only if you reused a key across different `socialAccountId` paths.                       |
| 429    | `RATE_LIMITED`         | Per-key write budget exhausted. Honor `Retry-After`.                                                                                                                                                                      |
| 500    | `INTERNAL`             | Server-side failure mid-transaction. The cancellation is atomic — either every queued post was canceled and the account is `disconnected`, or nothing changed. Safe to retry. `requestId` correlates against Layers logs. |
| 503    | `KILL_SWITCH`          | Your key, your org, or the global API integration has been disabled. `details.scope` is `key`, `organization`, or `global`.                                                                                               |

For leased accounts, prefer [`DELETE /v1/leased-accounts/:id`](/docs/api/reference/leased-accounts/release-leased-account) - it releases the billing relationship in addition to disconnecting. Calling this endpoint on a leased account succeeds (the account is marked disconnected) but does not release the lease.

## See also [#see-also]

* [`GET /v1/projects/:id/social-accounts`](/docs/api/reference/social-accounts/list-social-accounts) - check status before revoking
* [`DELETE /v1/leased-accounts/:id`](/docs/api/reference/leased-accounts/release-leased-account) - release leased accounts