Forcing a User to Logout

Overview

Forcing a logout allows you to remotely end a user's session in the mobile app. Common reasons include an expired session, a disabled account, or a suspected security issue.

IMPORTANT: Forcing a logout does not disable the user's account. To prevent the user from logging back in, your login endpoint, POST /authenticate, must also reject their credentials.

The mobile app checks whether a user's session is still valid during sync events by calling your server's user authentication endpoint. Your server controls what that endpoint returns, so to force a logout, you change your server’s response the next time the mobile app checks in.

How It Works

A forced logout is a three-step process:

The mobile app verifies the user’s session during sync events by calling GET /authenticate/{token}, or PUT /authenticate/{token} when the user changes a custom setting.
To log a user out, your server returns a 401 Unauthorized response from these endpoints.
When the mobile app receives the 401, it immediately deletes the locally stored api_token and displays the login screen. The user must log in again to receive a new token.

No additional calls are required. To make the logout take effect immediately, you can also call User Refresh.

WARNING: The mobile app triggers a logout only on a 401 response. Other 4xx or 5xx status codes do not log the user out.

Forcing a Logout

Step 1: Identify the Session to Invalidate

Determine which user or api_token to invalidate.

The mobile app behaves the same way regardless of the reason for the logout. Only the scope of tokens you invalidate changes.

Scenario	Action
Session expired	Return `401` for the expired token on the next verification
Account disabled by an administrator	Return `401` for all tokens associated with that account, and reject the account at login
Suspected security breach	Return `401` for the compromised token immediately, then call User Refresh for that user

Step 2: Update Your User Authentication Logic

On your server, locate the handlers for both verification endpoints: GET /authenticate/{token} and PUT /authenticate/{token}. The Platform calls PUT when a user changes their custom settings, and a 401 from either endpoint logs the user out.

Add logic to both handlers so that, for the tokens you want to invalidate, the endpoint returns a 401 Unauthorized response instead of a success response.

IMPORTANT: Scope this logic to only the tokens you intend to invalidate. If either endpoint returns 401 for tokens that should still be valid, those users are logged out unintentionally.

Example:

[HttpGet("authenticate/{token}")]
public IActionResult Authenticate(string token)
{
    if (IsTokenInvalid(token))
    {
        return Unauthorized(); // returns HTTP 401
    }

    // existing valid-session logic
    return Ok(userSessionData);
}

[HttpPut("authenticate/{token}")]
public IActionResult UpdateSettings(string token, [FromBody] CustomSettings settings)
{
    if (IsTokenInvalid(token))
    {
        return Unauthorized(); // returns HTTP 401
    }

    // existing settings-update logic
    return Ok(userSessionData);
}

If you are disabling an account, also update your login endpoint, POST /authenticate, to reject that user. Otherwise, the user is logged out but can log back in immediately.

[HttpPost("authenticate")]
public IActionResult Login([FromBody] LoginRequest request)
{
    if (IsAccountDisabled(request.Username))
    {
        return Unauthorized(); // rejects login for disabled accounts
    }

    // existing login logic
    return Ok(loginResponse);
}

Step 3: Trigger or Wait for the Next Sync Event

The mobile app verifies the session during sync events. At the next sync event after you update your server, the mobile app receives the 401, deletes its locally stored api_token, and returns the user to the login screen. To make the logout take effect immediately, trigger the sync event yourself with User Refresh.

Trigger a Sync Event with User Refresh

Send a POST request to the User Refresh endpoint, /api/v1/users/{username}/updates, for the user you are logging out. The Platform sends a silent push notification to that user's mobile app, which starts a sync event right away.

IMPORTANT: User Refresh is delivered through push notifications. If the user has push notifications disabled, the logout takes effect at the next sync event the user triggers instead.

NOTE: User Refresh is rate limited to 300 requests per 5 minutes. Requests over this limit receive an HTTP 429 response. When logging out many users at once, space out your requests.

For more information, refer to our User Refresh Guide.

Wait for a User-Triggered Sync Event

Without User Refresh, sync events are triggered by various actions in the mobile app rather than on a fixed schedule. Common triggers include backgrounding and reopening the mobile app, navigating to Settings and back to the Dashboard, and changing a custom setting.

NOTE: Because user-triggered sync events depend on user activity, there is no set time between updating your server and the logout taking effect.

Step 4: Confirm the Logout

Open the mobile app on a test device and log in as a user.
Call GET /authenticate/{token} for the affected user’s token and confirm it returns 401 Unauthorized.
Call User Refresh for the user, or navigate to Settings and back to the Dashboard in the mobile app, to trigger a sync event.
Confirm the mobile app returns to the login screen.