Skip to main content
Privy allows your app to freeze a user via their Privy user ID. Freezing is reversible. It suspends a user’s access without deleting their account, linked accounts, or embedded wallets. When your app freezes a user, Privy:
  • Blocks the user from logging in to your app
  • Revokes all of the user’s active sessions
  • Prevents the user from refreshing their access token
  • Keeps the user’s Privy ID, linked accounts, and embedded wallets unchanged
When your app unfreezes the user, the user can log in again. Privy does not restore revoked sessions, so the user must log in again.
Access tokens issued before the freeze remain valid until they expire. If your backend verifies access tokens itself, token verification alone does not enforce a freeze.

​
Freezing versus other controls

Freeze a user to pause their access, such as during an investigation of suspicious activity. Use the denylist to stop an identifier from logging in or creating accounts.

​
Freezing a user

Make a POST request to:
Replace <user-id> with the user’s Privy ID, in the format did:privy:XXXXXX.Authenticate with your app ID and app secret. Send an empty JSON body:
A successful request returns a 200 status code:

​
Unfreezing a user

Make a DELETE request to the same path:
A successful request returns a 200 status code with {"success": true}.

​
Checking whether a user is frozen

Make a GET request to get the user by ID. The response includes frozen_at, the Unix timestamp in seconds of when the user was frozen. The value is null if the user is not frozen.
A frozen user’s response includes the freeze time:
Only GET /v1/users/{user_id} returns frozen_at. Other user endpoints, webhooks, and client SDK user objects do not include it.

​
Behavior and errors

  • Idempotent requests: Repeating a freeze or unfreeze request returns a 200 status code. Freezing an already frozen user keeps the original freeze time, so frozen_at always shows when the freeze started. Your app can safely retry either request.
  • Unknown users: The API returns a 404 status code if the user does not exist or belongs to another app.
  • Authentication: Missing or invalid app credentials return a 401 status code.
  • Server errors: Retry a freeze request that returns a 5xx status code. The user may already be frozen.
  • Activity logs: Each freeze or unfreeze appears in your organization’s Activity logs in the Privy dashboard and is attributed to an app secret.
See the API reference for freezing and unfreezing users.