Partner Integration Guide

Welcome to the Bifrost Partner API. This guide will walk you through everything you need to integrate your platform with Bifrost — from setting up encryption to creating guilds and managing game server billing.

How the Partner API Works

Unlike the standard Bifrost API (which uses OAuth 2.0 tokens), the Partner API uses AES-256-GCM encryption for authentication. Instead of sending a bearer token, you encrypt your entire request payload with your unique encryption key. If the server can decrypt it, that proves you are who you say you are.

What You'll Need

Encryption Guide

Every Partner API request requires you to encrypt your JSON payload using AES-256-GCM. This is an industry-standard authenticated encryption algorithm — it both encrypts your data and verifies it hasn't been tampered with.

[12-byte IV][ciphertext][16-byte auth tag]  →  Base64 encode  →  encryptedData

Encryption Code Examples

Here's how to encrypt a payload in each language. You can copy this directly into your project:

# Encryption must be done in code before the cURL call.
# Here's a complete Node.js script that encrypts and sends:

node -e "
const crypto = require('crypto');
const https = require('https');

// Your credentials
const PARTNER_ID = 'your-partner-id';
const KEY_BASE64 = 'YOUR_BASE64_ENCRYPTION_KEY';

// Build the payload
const payload = {
  action: 'CREATE',
  gameServerId: 'your-server-uuid',
  mode: 'LIVE',
  timestamp: Date.now(),
  nonce: crypto.randomBytes(16).toString('hex')
};

// Encrypt
const key = Buffer.from(KEY_BASE64, 'base64');
const iv = crypto.randomBytes(12);
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
const ciphertext = Buffer.concat([
  cipher.update(JSON.stringify(payload), 'utf8'),
  cipher.final()
]);
const tag = cipher.getAuthTag();
const encrypted = Buffer.concat([iv, ciphertext, tag]).toString('base64');

console.log('Encrypted payload:', encrypted);
console.log('Length:', encrypted.length, 'characters');
"

Required Security Fields

Every encrypted payload — regardless of which endpoint you're calling — must include these two fields to prevent replay attacks:

{
  "timestamp": 1705849200000,
  "nonce": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  ...your other fields here...
}

Available Partner Endpoints

The Partner API provides two main endpoints. Click on each to see full documentation with request/response schemas and code examples.

Server Billing Status Lifecycle

Every game server has a billing status. The Partner API lets you transition servers between these statuses. Here's what each status means and which transitions are allowed:

Guild Creation Payload Reference

When calling partnerCreateGuild, the JSON you encrypt must follow this exact structure:

// This is the JSON you encrypt — NOT the GraphQL query
{
  "user": {
    "email": "[email protected]",
    "username": "CommunityOwner",
    "firstName": "John",
    "lastName": "Doe",
    "discordId": "123456789012345678"
  },
  "guild": {
    "name": "My Awesome Community",
    "abbreviation": "MAC",
    "discordUrl": "https://discord.gg/example",
    "description": "A friendly gaming community",
    "websiteUrl": "https://example.com",
    "countries": ["GB", "US"],
    "is18Plus": true,
    "isRecruiting": true,
    "isCompetitive": false,
    "isPcPlayers": true,
    "isConsolePlayers": false
  },
  "metadata": {
    "ownerId": "[email protected]"
  },
  "options": {
    "sendWelcomeEmail": false
  },
  "timestamp": 1705849200000,
  "nonce": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

User Fields

Guild Fields

Options & Metadata

Server Action Payload Reference

When calling partnerServerAction, the JSON you encrypt depends on the action you want to perform:

CREATE — Register a new game server

This is the main action for onboarding servers. It creates a fully configured game server on the Bifrost platform, links it to your partner guild, and activates billing. You must have already created a guild via partnerCreateGuild before creating servers.

{
  "action": "CREATE",
  "ownerId": "[email protected]",
  "serverGameType": "HLL",
  "serverName": "My Community Server #1",
  "serverIP": "203.0.113.50",
  "serverQueryPort": 27015,
  "serverRCONPort": 27020,
  "serverRCONPassword": "MySecureRconPass123!",
  "serverCountry": "US",
  "serverTimezone": "America/New_York",
  "serverPlatform": "PC",
  "mode": "LIVE",
  "timestamp": 1705849200000,
  "nonce": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

CHANGE_STATUS — Change a server's billing state

{
  "action": "CHANGE_STATUS",
  "ownerId": "[email protected]",
  "gameServerId": "server-uuid-from-create-response",
  "status": "NOPAYMENT",
  "reason": "Payment method declined",
  "timestamp": 1705849200000,
  "nonce": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

DELETE — Cancel a server permanently

Permanently cancels a server. The server record is not deleted from the database — it is set to CANCELLED status and deactivated. This is a terminal state and cannot be reversed.

{
  "action": "DELETE",
  "ownerId": "[email protected]",
  "gameServerId": "server-uuid-from-create-response",
  "reason": "Customer cancelled subscription",
  "timestamp": 1705849200000,
  "nonce": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

CHANGE_EMAIL — Update a guild owner's email

Updates the guild owner's email address across the identity provider (Keycloak), the database, and the guild metadata — all atomically. If either the identity provider or database update fails, everything is rolled back. The user's login email changes immediately. Use this when a customer changes their email address.

{
  "action": "CHANGE_EMAIL",
  "ownerId": "[email protected]",
  "newEmail": "[email protected]",
  "timestamp": 1705849200000,
  "nonce": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

CREATE Action Fields

CHANGE_STATUS & DELETE Action Fields

CHANGE_EMAIL Action Fields

Error Codes Reference

Both partner endpoints return a statusCode field that follows HTTP conventions. Here's what each code means and what to do about it:

Troubleshooting