BookStackApp/BookStack · error · ApiAuthException

errors.email_confirmation_awaiting

Error message

errors.email_confirmation_awaiting

What it means

getAuthorisedUserFromRequest() checks whether the token's user is still awaiting email confirmation via LoginService::awaitingEmailConfirmation(). If so, it throws ApiAuthException with the translated message errors.email_confirmation_awaiting, blocking API access until the email address is confirmed.

Source

Thrown at app/Api/ApiTokenGuard.php:92

    /**
     * Check the API token in the request and fetch a valid authorised user.
     *
     * @throws ApiAuthException
     */
    protected function getAuthorisedUserFromRequest(): Authenticatable
    {
        $authToken = trim($this->request->headers->get('Authorization', ''));
        $this->validateTokenHeaderValue($authToken);

        [$id, $secret] = explode(':', str_replace('Token ', '', $authToken));
        $token = ApiToken::query()
            ->where('token_id', '=', $id)
            ->with(['user'])->first();

        $this->validateToken($token, $secret);

        if ($this->loginService->awaitingEmailConfirmation($token->user)) {
            throw new ApiAuthException(trans('errors.email_confirmation_awaiting'));
        }

        return $token->user;
    }

    /**
     * Validate the format of the token header value string.
     *
     * @throws ApiAuthException
     */
    protected function validateTokenHeaderValue(string $authToken): void
    {
        if (empty($authToken)) {
            throw new ApiAuthException(trans('errors.api_no_authorization_found'));
        }

        if (!str_contains($authToken, ':') || !str_starts_with($authToken, 'Token ')) {
            throw new ApiAuthException(trans('errors.api_bad_authorization_format'));

View on GitHub (pinned to 18f8469a1c)

Solutions

1. Have the user open the email-confirmation link sent to their address, then retry the API call.
2. Resend the confirmation email from the admin user management page if the link expired.
3. An admin can manually confirm/activate the user in the admin area.
4. Check the instance's mail configuration (SMTP logs) if confirmation emails are not arriving.

try {
    $response = $client->get($apiUrl);
} catch (ApiAuthException $e) {
    if (str_contains($e->getMessage(), 'email_confirmation_awaiting')) {
        // prompt user to confirm email, then retry after confirmation
    }
    throw $e;
}

When it happens

Trigger: API request with a syntactically valid token id:secret pair, validateToken() passing, but the owning user has not completed email confirmation (new registration or recent email change) while email confirmation is required by the instance.

Common situations: Freshly registered API users on instances with REQUIRE_EMAIL_CONFIRMATION enabled; users who changed their email address and did not click the confirmation link; automated integrations created before the user confirmed; mail delivery failures leaving confirmation emails unopened.

Related errors

• Unauthorized
• errors.api_no_authorization_found
• errors.api_bad_authorization_format
• errors.api_user_token_not_found
• errors.api_incorrect_token_secret

AI-assisted analysis of BookStackApp/BookStack@18f8469a1c (2026-09-02). Data as JSON: /api/errors/c55c9a2dbab89308. Report an issue: GitHub.