DELETE /v1/social-accounts/:socialAccountId

DELETE/v1/social-accounts/:socialAccountId

Phase 1stable

Auth: Bearer
Scope: social:write

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 is the better endpoint - it releases the billing as well.

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.

Path

socialAccountId
stringrequired
Account to revoke.

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

Example request

curl -X DELETE https://api.layers.com/v1/social-accounts/sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e \
  -H "Authorization: Bearer lp_..."

const result = await layers.social.revoke({
  socialAccountId: "sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e",
});

console.log(`Canceled ${result.canceledScheduledPosts} queued posts.`);

result = layers.social.revoke(
    social_account_id="sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e",
)

Response

200Revoked

{
  "socialAccountId": "sa_9c1e42a0-b7f3-4e5d-a2c1-8b4f5e6c7d8e",
  "status": "disconnected",
  "disconnectedReason": "revoked_by_partner",
  "canceledScheduledPosts": 4,
  "disconnectedAt": "2026-04-18T19:15:02Z"
}

Errors

See 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 partner API has been disabled. `details.scope` is `key`, `organization`, or `global`.

For leased accounts, prefer DELETE /v1/leased-accounts/:id - 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.

DELETE /v1/social-accounts/:socialAccountId

Example request

Response

Errors

See also

On this page