Platform Moderation

Get ban status for a user

get

/users/{address}/bans

Returns whether the specified user address would currently be rejected by a platform ban — its own, or one matching the device the address is recorded on.

This endpoint is public — no authentication required. It is intended for clients to check their own ban status before attempting to connect.

Close to what token retrieval enforces, but not identical

This endpoint receives only an address, so its device term is always the address's last recorded device. Token paths prefer the device identifier the request itself carries and fall back to the recorded one only when it has none. Where a request arrives with a device that differs from the recorded one, the two can disagree in both directions.

So a user banned on one wallet who reconnects under a different wallet from the same recorded device is reported as banned here and rejected at token issuance — but treat this endpoint as the source for user-facing ban messaging, not as a prediction of whether a specific connection will be accepted. Token issuance stays authoritative for a concrete request.

The ban record is only returned for the address's own ban

matchedOn says which identifier matched. When it is device, the response contains isBanned: true and no ban object: the matching row belongs to another player, and publishing it on an unauthenticated route would disclose whose wallet is banned. The full record — reason, expiry, custom message — is returned only when matchedOn is address. Where both exist, the address's own ban is the one reported.

bannedDeviceId is never returned on this route, whatever matchedOn says: it is a stable cross-wallet machine identifier and this endpoint is unauthenticated. Moderator tooling reads it from the moderator-gated GET /bans.

A client can use matchedOn to word the notice: an address match has a reason and an expiry to show, a device match has neither.

Because the route is unauthenticated, any address can be tested for device coverage. That is an accepted trade-off for being able to tell banned players why they are blocked.

Moderator tooling that needs the full picture, including each ban's device snapshot, should use the moderator-gated GET /bans.

Path parameters

addressstringRequired

Ethereum address to check

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Ban status retrieved

application/json

500

Internal server error

application/json

get/users/{address}/bans

GET /users/{address}/bans HTTP/1.1
Host: comms-gatekeeper.decentraland.org
Accept: */*

{
  "data": {
    "isBanned": true,
    "matchedOn": "address",
    "ban": {
      "id": "text",
      "bannedAddress": "text",
      "bannedBy": "text",
      "reason": "text",
      "customMessage": "text",
      "bannedAt": "2026-08-11T14:48:16.041Z",
      "expiresAt": "2026-08-11T14:48:16.041Z",
      "liftedAt": "2026-08-11T14:48:16.041Z",
      "liftedBy": "text",
      "createdAt": "2026-08-11T14:48:16.041Z"
    }
  }
}

Ban a player (platform-wide)

post

/users/{address}/bans

Issues a platform-level ban for the specified user address. A platform-banned user will be rejected at token issuance time and cannot enter any Genesis City scene or island room until the ban expires or is lifted.

Requires Signed Fetch authentication plus a valid moderator role, verified server-side via moderatorAuthMiddleware.

The ban can be permanent (no duration) or timed. An optional customMessage is surfaced to the player at rejection time.

The player's recorded device id (from their connection info) is banned alongside the address when one is known, so the ban follows the device across wallets. This is best-effort: a player who has never connected, or whose client sent no device identifier, is banned by address only.

The resulting device coverage is reflected by GET /users/{address}/bans, which reports a device match as isBanned: true without disclosing the matching ban record.

Authorizations

x-identitystringRequired

Signed Fetch authentication for scene-based requests. Requires a chain of identity headers:

x-identity-auth-chain-0: Signer information
x-identity-auth-chain-1: Ephemeral key information
x-identity-auth-chain-2: Signed entity information
x-identity-timestamp: Request timestamp
x-identity-metadata: Request metadata Used for authentication from decentraland-kernel-scene.

Path parameters

addressstringRequired

Ethereum address of the user to ban

Pattern: ^0x[a-fA-F0-9]{40}$

Body

reasonstring · min: 1Required

Reason for the ban (internal, logged)

durationnumberOptional

Ban duration in seconds. Must be positive. Omit for a permanent ban.

customMessagestringOptional

Optional message shown to the player on rejection

Responses

201

Ban created successfully

application/json

400

Invalid request body

application/json

401

Unauthorized — invalid Signed Fetch or missing moderator role

application/json

403

Forbidden — caller does not have the moderator role

application/json

500

Internal server error

application/json

post/users/{address}/bans

POST /users/{address}/bans HTTP/1.1
Host: comms-gatekeeper.decentraland.org
x-identity: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "reason": "text",
  "duration": 1,
  "customMessage": "text"
}

{
  "data": {
    "id": "text",
    "bannedAddress": "text",
    "bannedBy": "text",
    "reason": "text",
    "customMessage": "text",
    "bannedAt": "2026-08-11T14:48:16.041Z",
    "expiresAt": "2026-08-11T14:48:16.041Z",
    "liftedAt": "2026-08-11T14:48:16.041Z",
    "liftedBy": "text",
    "createdAt": "2026-08-11T14:48:16.041Z",
    "bannedDeviceId": "text"
  }
}

Lift a platform-wide ban

delete

/users/{address}/bans

Removes the active platform-level ban for the specified user address. The user will be able to obtain LiveKit tokens again on their next connection attempt.

Requires Signed Fetch authentication plus a valid moderator role.

Authorizations

x-identitystringRequired

Signed Fetch authentication for scene-based requests. Requires a chain of identity headers:

x-identity-auth-chain-0: Signer information
x-identity-auth-chain-1: Ephemeral key information
x-identity-auth-chain-2: Signed entity information
x-identity-timestamp: Request timestamp
x-identity-metadata: Request metadata Used for authentication from decentraland-kernel-scene.

Path parameters

addressstringRequired

Ethereum address of the user whose ban to lift

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

204

Ban lifted successfully

No content

401

Unauthorized — invalid Signed Fetch or missing moderator role

application/json

403

Forbidden — caller does not have the moderator role

application/json

404

No active ban found for this address

application/json

500

Internal server error

application/json

delete/users/{address}/bans

DELETE /users/{address}/bans HTTP/1.1
Host: comms-gatekeeper.decentraland.org
x-identity: YOUR_API_KEY
Accept: */*

No content

Get warnings for a user

get

/users/{address}/warnings

Returns all warnings on record for the specified user address.

Requires Signed Fetch authentication plus a valid moderator role.

Authorizations

x-identitystringRequired

Signed Fetch authentication for scene-based requests. Requires a chain of identity headers:

x-identity-auth-chain-0: Signer information
x-identity-auth-chain-1: Ephemeral key information
x-identity-auth-chain-2: Signed entity information
x-identity-timestamp: Request timestamp
x-identity-metadata: Request metadata Used for authentication from decentraland-kernel-scene.

Path parameters

addressstringRequired

Ethereum address to look up

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Warnings retrieved successfully

application/json

401

Unauthorized — invalid Signed Fetch or missing moderator role

application/json

403

Forbidden — caller does not have the moderator role

application/json

500

Internal server error

application/json

get/users/{address}/warnings

GET /users/{address}/warnings HTTP/1.1
Host: comms-gatekeeper.decentraland.org
x-identity: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "warnedAddress": "text",
      "warnedBy": "text",
      "reason": "text",
      "warnedAt": "2026-08-11T14:48:16.041Z",
      "createdAt": "2026-08-11T14:48:16.041Z"
    }
  ]
}

Issue a warning to a player

post

/users/{address}/warnings

Records a formal warning for the specified user. Warnings are part of a graduated moderation system and can inform future ban decisions.

Requires Signed Fetch authentication plus a valid moderator role.

Authorizations

x-identitystringRequired

Signed Fetch authentication for scene-based requests. Requires a chain of identity headers:

x-identity-auth-chain-0: Signer information
x-identity-auth-chain-1: Ephemeral key information
x-identity-auth-chain-2: Signed entity information
x-identity-timestamp: Request timestamp
x-identity-metadata: Request metadata Used for authentication from decentraland-kernel-scene.

Path parameters

addressstringRequired

Ethereum address of the user to warn

Pattern: ^0x[a-fA-F0-9]{40}$

Body

reasonstring · min: 1Required

Reason for the warning

Responses

201

Warning issued successfully

application/json

400

Invalid request body

application/json

401

Unauthorized — invalid Signed Fetch or missing moderator role

application/json

403

Forbidden — caller does not have the moderator role

application/json

500

Internal server error

application/json

post/users/{address}/warnings

POST /users/{address}/warnings HTTP/1.1
Host: comms-gatekeeper.decentraland.org
x-identity: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "reason": "text"
}

{
  "data": {
    "id": "text",
    "warnedAddress": "text",
    "warnedBy": "text",
    "reason": "text",
    "warnedAt": "2026-08-11T14:48:16.041Z",
    "createdAt": "2026-08-11T14:48:16.041Z"
  }
}

List all active platform bans

get

/bans

Returns a list of all currently active platform-level bans.

Requires Signed Fetch authentication plus a valid moderator role. Not paginated — intended for moderator tooling that needs a full snapshot.

Authorizations

x-identitystringRequired

Signed Fetch authentication for scene-based requests. Requires a chain of identity headers:

x-identity-auth-chain-0: Signer information
x-identity-auth-chain-1: Ephemeral key information
x-identity-auth-chain-2: Signed entity information
x-identity-timestamp: Request timestamp
x-identity-metadata: Request metadata Used for authentication from decentraland-kernel-scene.

Responses

200

Bans retrieved successfully

application/json

401

Unauthorized — invalid Signed Fetch or missing moderator role

application/json

403

Forbidden — caller does not have the moderator role

application/json

500

Internal server error

application/json

get/bans

GET /bans HTTP/1.1
Host: comms-gatekeeper.decentraland.org
x-identity: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "bannedAddress": "text",
      "bannedBy": "text",
      "reason": "text",
      "customMessage": "text",
      "bannedAt": "2026-08-11T14:48:16.041Z",
      "expiresAt": "2026-08-11T14:48:16.041Z",
      "liftedAt": "2026-08-11T14:48:16.041Z",
      "liftedBy": "text",
      "createdAt": "2026-08-11T14:48:16.041Z",
      "bannedDeviceId": "text"
    }
  ]
}

Check if a user is banned from a world parcel

get

/worlds/{worldName}/parcels/{baseParcel}/users/{address}/ban-status

Service-to-service endpoint used by Worlds Content Server to verify whether a user is banned from a specific world parcel before issuing a LiveKit token.

Requires Bearer token authentication (COMMS_GATEKEEPER_AUTH_TOKEN). Not intended for direct client use.

Authorizations

AuthorizationstringRequired

Bearer token authentication for service-to-service communication.

Path parameters

worldNamestringRequired

World identifier

baseParcelstringRequired

Base parcel position (e.g. "0,0")

addressstringRequired

Ethereum address of the user to check

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Ban status retrieved

application/json

isBannedbooleanRequired

true if the user is banned from this world parcel

401

Unauthorized — invalid or missing Bearer token

application/json

500

Internal server error

application/json

get/worlds/{worldName}/parcels/{baseParcel}/users/{address}/ban-status

GET /worlds/{worldName}/parcels/{baseParcel}/users/{address}/ban-status HTTP/1.1
Host: comms-gatekeeper.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "isBanned": true
}

PreviousCast 2.0 NextArchipelago Workers

Last updated 5 days ago