Create Guild — partnerCreateGuild | Bifrost Developer Center

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

partnerCreateGuild

Creates a new guild and its owner account in a single request. This is the primary way for partners to onboard new communities into the Bifrost platform.

Operation Type

Mutation

Rate Limit: 10 requests per minute per partner

Rate limits are applied per partner (identified by partnerId). Exceeding the limit returns a 429 response.

Important usage notes

metadata.ownerId is required and must match user.email. This is the persistent identifier used to target this guild in all future server actions (CREATE, CHANGE_STATUS, DELETE, CHANGE_EMAIL). One ownerId can only be associated with one guild per partner.
If an email address, guild abbreviation, or ownerId (per partner) is already in use, the request will return statusCode 403 (conflict).
A 14-day premium trial subscription is automatically created for new guilds.
If sendWelcomeEmail is true, no temporaryPassword is returned — the user receives a password reset link by email instead.
The guild owner's email is managed by the partner — the user cannot change it themselves in the control panel. Use the Change Email endpoint to update it.

Input Fields

Field	Type	Required	Description
`partnerId`	String!	Required	Your unique partner identifier. This was provided to you when your partner account was created.
`encryptedData`	String!	Required	Your JSON payload encrypted with AES-256-GCM using your partner encryption key, then Base64 encoded. See the Encryption Guide for details.

Encrypted Payload Fields

Field	Type	Required	Description
`timestamp`	Number	Required	Current time in Unix milliseconds. Must be within 5 minutes of server time.
`nonce`	String	Required	A unique random string, at least 16 characters. Use a UUID or similar.
`user.email`	String	Required	Email address for the guild owner account. Must be unique across the platform.
`user.username`	String	Required	Display name for the guild owner account.
`user.firstName`	String	Required	First name of the guild owner.
`user.lastName`	String	Required	Last name of the guild owner.
`guild.name`	String	Required	Display name of the guild / community.
`guild.abbreviation`	String	Required	Short abbreviation (e.g. "MAC"). Must be unique across the platform.
`guild.discordUrl`	String	Optional	Discord server invite URL (e.g. https://discord.gg/example).
`guild.countries`	String[]	Optional	Array of ISO 3166-1 alpha-2 country codes (e.g. ["GB", "US"]).
`guild.is18Plus`	Boolean	Optional	Whether the community is 18+ only. Defaults to false.
`guild.isRecruiting`	Boolean	Optional	Whether the community is actively recruiting. Defaults to false.
`guild.isCompetitive`	Boolean	Optional	Whether this is a competitive community. Defaults to false.
`guild.isPcPlayers`	Boolean	Optional	Whether the community includes PC players. Defaults to false.
`guild.isConsolePlayers`	Boolean	Optional	Whether the community includes console players. Defaults to false.
`metadata.ownerId`	String	Required	Must match user.email. Persistent identifier used to target this guild in all future API calls.
`options.sendWelcomeEmail`	Boolean	Optional	If true, sends a welcome email with password reset link instead of returning a temporary password. Defaults to false.

These fields make up the JSON payload that is encrypted with AES-256-GCM before being sent as encryptedData.

Code Examples

# Step 1: Encrypt your payload (see Encryption Guide)
# Step 2: Send the encrypted payload to the API

curl -X POST https://api.dev.bifrostgaming.com/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation PartnerCreateGuild($input: PartnerCreateGuildInput!) { partnerCreateGuild(input: $input) { success statusCode message guild { id name abbreviation inviteCode } user { id email username keycloakId temporaryPassword } } }",
    "variables": {
      "input": {
        "partnerId": "your-partner-id",
        "encryptedData": "BASE64_ENCRYPTED_PAYLOAD_HERE"
      }
    }
  }'

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

Open Postman and click Import (top-left)
Drag and drop the downloaded .json file, or click Upload Files and select it
Click Import to confirm
The collection appears in your sidebar — expand it and select the request
In the Body tab, update the placeholder values (your-partner-id, etc.) with your actual credentials
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": {
    "partnerCreateGuild": {
      "success": true,
      "statusCode": 201,
      "message": "Guild 'My Awesome Community' created successfully with owner [email protected]",
      "guild": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "My Awesome Community",
        "abbreviation": "MAC",
        "inviteCode": "xK7mN2pQ"
      },
      "user": {
        "id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
        "email": "[email protected]",
        "username": "CommunityOwner",
        "keycloakId": "9a8b7c6d-5e4f-3210-fedc-ba9876543210",
        "temporaryPassword": "Temp#Pass123!"
      }
    }
  }
}

Error Responses

Response Fields

Field	Type	Required	Description
`success`	Boolean	Required	true if the guild and owner were created successfully.
`statusCode`	Int	Required	HTTP-style status code. 201 = created, 400 = bad request, 401 = unauthorized, 403 = conflict, 500 = server error.
`message`	String	Required	A human-readable description of the result. Always check this if success is false.
`guild`	Object	Optional	The created guild details: id, name, abbreviation, inviteCode. Only present on success.
`user`	Object	Optional	The created owner account: id, email, username, keycloakId, temporaryPassword (only if sendWelcomeEmail is false).

In partnership with

Brilliant game servers for communities large and small.

Get yours today!

A Shrapnelworks product