users_users_ban

Tool

users_users_ban

Ban an end user by stamping `bannedAt` and revoking their live sessions.

Ban an end user by stamping `bannedAt` and revoking their live sessions. Banned users are refused at sign-in. Banning an already-banned user refreshes the stamp.

Behavior

HTTP: POST /users/users/:userId/ban

Arguments

Name	Type	Required	Description
userId	string	•	The opaque user id returned by users_users_create or _list.

Response

Field	Type	Always	Description
id	string	•	Id of this end user. Pass it to any users_users_* tool.
kind	string	•	What kind of person this row is: 'account' (can sign in) or 'contact' (known to the Product, no credential, never signed in). A contact is hidden from the default users_users_list view and is never counted as a retained user.
name	string	•	The user's display name. Null when nobody set one.
tags	array	•	Free labels on this person, stored trimmed, lowercased and de-duplicated.
stage	string	•	The relationship stage, in funnel order: new, contacted, replied, engaged, converted, lost. A real change publishes `users/user.stage-changed`.
bannedAt	string	•	When the user was banned (ISO 8601). Null while they are not banned.
erasedAt	string	•	When this user's personal data was purged for good (ISO 8601). Null while it is intact.
imageUrl	string	•	URL of the user's avatar. Null when there is none.
testUser	boolean	•	Whether this is a test fixture — excluded from metering and from the default listing.
createdAt	string	•	When the user was created (ISO 8601).
deletedAt	string	•	When the user was soft-deleted (ISO 8601). Null while the account is live.
productId	string	•	Product this user belongs to. Never an input — it comes from the calling identity.
updatedAt	string	•	When the user was last changed (ISO 8601).
mergedFrom	string	•	Set when you asked for an id that was merged into this account — it is the id you asked for, and this is the row it now lives in. Null on every ordinary read.
waitlisted	boolean	•	Whether this user is still on the waitlist and cannot sign in yet.
identifiers	array	•	Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
lastTouchAt	string	•	When this person was last touched — the most recent logged interaction (ISO 8601). Null when nobody has logged one. This is when the interaction HAPPENED, not when it was logged.
lockedUntil	string	•	When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
lastSignInAt	string	•	When the user last signed in (ISO 8601). Null if they never have.
primaryEmail	string	•	The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
requiresReset	boolean	•	Whether the user must set a new password at their next sign-in.
publicMetadata	object	•	Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
unsafeMetadata	object	•	Metadata the end user may write themselves. Treat it as untrusted.
privateMetadata	object	•	Metadata for the management plane only. Never reaches the end user or a token.
mergedIntoUserId	string	•	The user this person was merged INTO, when they were merged. Null for everybody else — follow it to find where their records went.
primaryIdentifierId	string	•	Id of the primary identifier row. Null when there is no primary identifier.
emailChangeLockedUntil	string	•	Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.

Try it

Ban an end user by stamping `bannedAt` and revoking their live sessions.

When to use

Ban an end user by stamping `bannedAt` and revoking their live sessions. Banned users are refused at sign-in. Banning an already-banned user refreshes the stamp.

Example

Ask your agent something like this:

Ban an end user by stamping `bannedAt` and revoking their live sessions.

The agent will invoke users_users_ban with these arguments:

{
  "userId": "<userId>"
}