Bifrost Bifrost
POSThttps://api.dev.bifrostgaming.com/v1/graphql

partnerAddRagnarokBan

v1

Insert a new ban into the Ragnarok ban registry on behalf of an adopting Bifrost guild. The Ragnarok registry is a partner-only ban list that is completely separate from the per-server Bifrost ban tables. Each insert generates a unique RagnarokBanId (UUID) and a human-readable RagnarokBanAppealCode in the format RK-XXXXXX (6 alphanumeric characters from a 32-char ambiguity-free alphabet). Both identifiers are returned to the caller and stored in the database alongside the ban. The adopting Bifrost guild is identified by its OAuth client ID (guildClientId, e.g. "guild-123-cad48d") — the resolver maps that to the internal Bifrost guild UUID server-side. A ban inserted against a given guildClientId applies to every game server owned by that guild: any player whose Team 17 ID matches an ACTIVE ban is kicked on connect from every server in the guild with the Ragnarok appeal message. Re-adopting the same (t17Id, guild) while an ACTIVE ban already exists is idempotent — the existing record is returned and no new appeal code is generated. The ORIGINATING community — the community on BARRICADE / Ragnarok that raised the ban — is tracked separately from the adopting Bifrost guild via playerBanGuildName / playerBanGuildDiscord and does NOT need to exist on the Bifrost system.

Operation Type

Mutation

Rate Limit: 60 requests / 60 seconds per partner

Important usage notes

  • playerBanType MUST be "PERMANENT" — the registry rejects any other value with a 400 error.
  • playerBanCategory MUST be "RACISM", "HOMOPHOBIA/ANTI-SEMITISM", or "CHEATING". Any other category is rejected with a 400 error.
  • playerBanPlatform MUST be "PC", "CONSOLE", or "ALL". Use a specific platform when the ban applies only there; use "ALL" for true-crossplay games so every guild (regardless of their platform mix) can adopt the ban.
  • gameType MUST be "HLL" or "HLLV". It is orthogonal to playerBanPlatform — both games run on both platforms, so supply both values.
  • playerBanSource MUST be "BARRICADE" or "RAGNAROK". Any other source is rejected.
  • guildClientId is REQUIRED — the adopting Bifrost guild is always identified by its OAuth client ID (e.g. "guild-123-cad48d"), which the guild owner pastes into BARRICADE. Bifrost guild UUIDs are NEVER exposed to partners. A 404 is returned if the guildClientId does not match an active Bifrost guild.
  • t17Id MUST be the player's Team 17 ID — this is the identifier enforced at connect time across every platform, and is required.
  • playerBanPlatformId is OPTIONAL. When supplied (Steam64 for PC, EOS ID for CONSOLE), it is stored alongside t17Id and used by the appeal flow at ragnarok.bifrostgaming.com: a player can enter their appeal code together with EITHER their T17 ID, Steam ID, or EOS ID, and the registry matches against t17Id OR playerBanPlatformId. Omit it if the partner does not have it.
  • The ORIGINATING community (playerBanGuildName / playerBanGuildDiscord) is always tracked separately from the adopting Bifrost guild. It does NOT need to exist on the Bifrost system and can be any community that raised the ban on BARRICADE / Ragnarok.
  • The ban is applied to every game server owned by the adopting Bifrost guild: any connecting player whose T17 ID matches an ACTIVE ban is kicked with the Ragnarok appeal message.
  • Pass the same externalBanId every time you propagate ONE ban to multiple adopting guilds. Doing so guarantees all adoptions share a single RK-XXXXXX appeal code — the banned player sees one consistent code across every guild that kicks them. Different BARRICADE bans for the same player should use different externalBanIds; each gets its own shared code.
  • Idempotency is keyed on (guild, externalBanId): a repeat call from the same guild with the same externalBanId returns the existing record — no new row, no new code. Without externalBanId, each call creates a fresh row with a fresh code, so BARRICADE is responsible for avoiding accidental duplicates on retries.
  • The RagnarokBanAppealCode is generated from a 32-character ambiguity-free alphabet (no 0/O, 1/I) so it can be read aloud without confusion.
  • createdAt and updatedAt are set automatically by the server.

Input Fields

FieldTypeRequiredDescription
partnerIdString!RequiredYour unique partner identifier.
partnerEncryptionKeyString!RequiredYour partner encryption key (Base64-encoded).
guildClientIdString!RequiredREQUIRED. The adopting Bifrost guild's OAuth client ID (e.g. "guild-123-cad48d") — the value the guild owner pasted into BARRICADE. The resolver maps this to the internal Bifrost guild UUID; a 404 is returned if no active Bifrost guild matches. This is the ONLY guild identifier BARRICADE should ever hold — Bifrost guild UUIDs are never exposed to partners.
externalBanIdStringOptionalOPTIONAL but strongly recommended. A stable partner-side identifier for the originating ban (e.g. BARRICADE's own ban UUID). When multiple guilds adopt the SAME partner ban, every call passes the same externalBanId and every adoption reuses a single RK-XXXXXX appeal code — so the banned player sees one consistent code across all guilds. If THIS guild has already adopted a ban with the given externalBanId, the call is idempotent and returns the existing record. If another guild has already adopted it, the first adoption's appeal code is reused for the new row. Omit only if you have no stable ID for the ban; in that case each call mints its own code.
playerBanGuildNameString!RequiredName of the ORIGINATING community (the community on BARRICADE / Ragnarok that raised the ban, free text). This is separate from the adopting Bifrost guild and does NOT need to exist on the Bifrost system.
playerBanGuildAdminNameStringOptionalOPTIONAL. Name of the admin / moderator inside the originating community who raised the ban. Shown on the adopting guild's UCP as "<admin> @ <community>". Free text; omit if the partner does not track this.
playerBanGuildDiscordStringOptionalDiscord server URL for the originating community (optional, free text).
t17IdString!RequiredREQUIRED. The banned player's Team 17 ID. This is the identifier enforced at connect time against every supported platform — partners MUST supply it.
playerBanPlatformIdStringOptionalOPTIONAL. The banned player's platform identifier — Steam64 for PC, EOS ID for CONSOLE. Stored separately from t17Id and used at ragnarok.bifrostgaming.com during the appeal flow: the player enters their appeal code plus EITHER their T17 ID, Steam ID, or EOS ID, and the registry matches against t17Id OR playerBanPlatformId. Omit if the partner does not have it.
playerNameStringOptionalDisplay name of the banned player at the time of the ban (optional).
playerBanTypeString!RequiredMUST be the literal string "PERMANENT". The Ragnarok registry only accepts permanent bans.
playerBanCategoryString!RequiredOne of "RACISM", "HOMOPHOBIA/ANTI-SEMITISM", or "CHEATING". The registry intentionally limits categories to these grounds.
playerBanPlatformString!RequiredOne of "PC", "CONSOLE", or "ALL". Use "PC" or "CONSOLE" when the ban is specific to a single platform. Use "ALL" for true-crossplay titles so the ban applies to every platform and is offered for adoption to every Bifrost guild regardless of platform mix.
gameTypeString!RequiredREQUIRED. One of "HLL" or "HLLV". Both games run on both platforms, so gameType and playerBanPlatform are orthogonal — supply both.
playerBanReasonString!RequiredFree-text reason for the ban. May be long-form (full incident write-ups are encouraged).
playerBanEvidence[String]OptionalArray of evidence URLs (screenshots, video links, log dumps, etc.). Defaults to an empty array.
playerBanSourceString!RequiredOne of "BARRICADE" or "RAGNAROK", identifying the partner tool that issued the ban.
playerBanStatusStringOptionalDefaults to "ACTIVE". The only other allowed value is "INACTIVE" (use partnerRemoveRagnarokBan to flip status).

Code Examples

# guildClientId identifies the ADOPTING Bifrost guild (the value the guild owner
# pasted into BARRICADE). playerBanGuildName identifies the ORIGINATING community
# that raised the ban, which may not exist on Bifrost at all.
curl -X POST https://api.dev.bifrostgaming.com/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation PartnerAddRagnarokBan($partnerId: String!, $partnerEncryptionKey: String!, $guildClientId: String!, $playerBanGuildName: String!, $playerBanGuildDiscord: String, $t17Id: String!, $playerBanType: String!, $playerBanCategory: String!, $playerBanPlatform: String!, $playerBanReason: String!, $playerBanSource: String!, $playerBanEvidence: [String!]) { partnerAddRagnarokBan(partnerId: $partnerId, partnerEncryptionKey: $partnerEncryptionKey, guildClientId: $guildClientId, playerBanGuildName: $playerBanGuildName, playerBanGuildDiscord: $playerBanGuildDiscord, t17Id: $t17Id, playerBanType: $playerBanType, playerBanCategory: $playerBanCategory, playerBanPlatform: $playerBanPlatform, playerBanReason: $playerBanReason, playerBanSource: $playerBanSource, playerBanEvidence: $playerBanEvidence) { ragnarokBanId ragnarokBanAppealCode playerBanStatus createdAt } }",
    "variables": {
      "partnerId": "your-partner-id",
      "partnerEncryptionKey": "your-base64-encryption-key",
      "guildClientId": "guild-123-cad48d",
      "externalBanId": "BRCD-2026-000123",
      "playerBanGuildName": "Some Community Not On Bifrost",
      "playerBanGuildAdminName": "MrAdminPerson",
      "playerBanGuildDiscord": "https://discord.gg/example",
      "t17Id": "00020000abc1234def5678901234abcd",
      "playerBanPlatformId": "76561198000000000",
      "playerBanType": "PERMANENT",
      "playerBanCategory": "RACISM",
      "playerBanPlatform": "PC",
      "gameType": "HLL",
      "playerBanReason": "Repeated racial slurs in team chat across multiple sessions. Full chat log attached.",
      "playerBanSource": "BARRICADE",
      "playerBanEvidence": [
        "https://example.com/evidence/screenshot1.png",
        "https://example.com/evidence/clip.mp4"
      ]
    }
  }'

Postman Collection

Download a ready-to-use Postman collection for this endpoint. Import it into Postman to start testing immediately.

How to import into Postman
  1. Open Postman and click Import (top-left)
  2. Drag and drop the downloaded .json file, or click Upload Files and select it
  3. Click Import to confirm
  4. The collection appears in your sidebar — expand it and select the request
  5. In the Body tab, update the placeholder values (your-partner-id, etc.) with your actual credentials
  6. Click Send

The collection uses Postman's GraphQL body type, which provides syntax highlighting and variable editing. Make sure your Postman version is 7.2+ for GraphQL support.

Success Response200

{
  "data": {
    "partnerAddRagnarokBan": {
      "ragnarokBanId": "9c54e3a2-7f8d-4a1b-9c2e-6a5d4e3f2b1c",
      "ragnarokBanAppealCode": "RK-K4M9Q2",
      "guildId": "48999d4d-41f3-4456-8dcb-4600af60e848",
      "playerBanGuildName": "Some Community Not On Bifrost",
      "playerBanGuildAdminName": "MrAdminPerson",
      "playerBanGuildDiscord": "https://discord.gg/example",
      "t17Id": "00020000abc1234def5678901234abcd",
      "playerBanPlatformId": "76561198000000000",
      "playerName": null,
      "playerBanType": "PERMANENT",
      "playerBanCategory": "RACISM",
      "playerBanPlatform": "PC",
      "playerBanReason": "Repeated racial slurs in team chat across multiple sessions.",
      "playerBanEvidence": [
        "https://example.com/evidence/screenshot1.png"
      ],
      "playerBanSource": "BARRICADE",
      "playerBanStatus": "ACTIVE",
      "removeBanReason": null,
      "createdAt": "2026-04-07T14:32:18.491Z",
      "updatedAt": "2026-04-07T14:32:18.491Z"
    }
  }
}

Error Responses

Response Fields

FieldTypeRequiredDescription
PartnerRagnarokBanPartnerRagnarokBanRequiredThe complete inserted ban record (same shape as partnerSearchRagnarokBans returns). Read ragnarokBanId and ragnarokBanAppealCode directly off this object — there is no separate envelope.

In partnership with

Qonzer Logo

Brilliant game servers for communities large and small.

Get yours today!

Shrapnelworks Logo

A Shrapnelworks product