🚨 Slack Error: 'two_factor_setup_required' — Cause, Fix, and Troubleshooting Guide

Overview

two_factor_setup_required means the request is being made with a user token whose account has not set up two-factor authentication, in a workspace that requires it. Slack blocks the call until 2FA is configured on that account.

{
    "ok": false,
    "error": "two_factor_setup_required"
}

Symptoms

• Only affects calls made with a user (xoxp-) token, not bot (xoxb-) tokens.
• Started after an admin enforced 2FA for the workspace.
• The same automation on a bot token is unaffected.

Common Root Causes

1. Workspace enforces 2FA and the user hasn’t enrolled

An admin turned on required two-factor auth; the account tied to the user token has no 2FA set up, so its token is gated.

2. Service/user account without 2FA

A shared “service user” account used to mint a user token was never enrolled in 2FA.

3. Recently invited user token used before enrolment

A newly created account produces a user token but the person hasn’t completed 2FA setup.

How to diagnose

Check the token type and identity:

printf '%s' "$SLACK_TOKEN" | cut -c1-5

xoxp-

curl -s https://slack.com/api/auth.test \
  -H "Authorization: Bearer $SLACK_TOKEN"

{"ok": false, "error": "two_factor_setup_required"}

A xoxp- prefix plus this error points squarely at the account’s missing 2FA.

Fixes

• Enable 2FA on the account that owns the user token (Account → Settings → Two-Factor Authentication), then retry.
• Prefer a bot token for ops automation. Bot tokens act as the app, not a human account, and are not gated by per-user 2FA enforcement.
• For unavoidable user-token flows, ensure the backing account is fully enrolled and kept compliant with workspace policy.

What to watch out for

• This is not a scope or invalid_auth problem — the token is valid, the account just isn’t 2FA-compliant.
• Building automation on a personal user token is fragile; enforced 2FA, password changes, and offboarding all break it. Bot tokens are the durable choice.
• If you must use a service account, document who owns it and keep its 2FA and recovery codes in your secret store.

Related

• Slack Error: ‘invalid_auth’
• Slack Error: ‘account_inactive’
• Securing Slack webhooks and tokens