Project Auth Tokens

Project Auth Tokens enable programmatic access to specific BetaHub projects for in-game reporting, launchers, and custom integrations. Unlike Personal Access Tokens which provide full account access, Project Auth Tokens are scoped to a single project with configurable permissions and rate limits.

What Are Project Auth Tokens?

Project Auth Tokens (tkn- prefix) are created by project owners to grant limited API access for specific use cases:

• In-game bug reporting through Unity, Unreal Engine, and other game engine plugins
• Game launcher integrations for automated feedback collection
• Public feedback forms with controlled access
• Third-party tools that need project-specific access

Key Differences from Personal Access Tokens

Creating Project Auth Tokens

Step 1: Navigate to Auth Tokens

1. Go to your project dashboard
2. Click Settings → Integrations in the sidebar
3. Select the Auth Tokens tab

Step 2: Create a New Token

1. Click the “New Token” button
2. Configure the token settings:
   • Token Name (required): Descriptive name (e.g., “Unity Plugin”, “Game Launcher”)
   • Permissions: Select what actions this token can perform
   • Rate Limits: Configure IP-based daily limits

Step 3: Copy and Store Token

Token Permissions

Configure what each token can do:

Bug Reporting:

• Can Create Bug Report - Allow bug/issue submission
• Limit Per Day - Daily limit per IP address (default: 8)

Feature Requests:

• Can Create Feature Request - Allow suggestion submission
• Limit Per Day - Daily limit per IP address (default: 8)

Support Tickets:

• Can Create Ticket - Allow support ticket submission
• Limit Per Day - Daily limit per IP address (default: 8)

Crash Reporting:

• Can Report Crash - Accept crash reports from Unreal Engine’s CrashReportClient
• Limit Per Day - Daily limit per IP address (default: 100)

Releases:

• Can Read Release List - Access to release information
• Can Create Release - Upload new versions (advanced use cases)

Rate Limiting and IP Tracking

Project Auth Tokens use IP-based rate limiting to prevent abuse:

How It Works:

• Each unique IP address is tracked separately
• Limits reset daily at midnight UTC
• Counters are maintained per token per IP per day

Default Limits:

• Bug reports: 8 bug reports per day per IP
• Feature requests: 8 feature requests per day per IP
• Support tickets: 8 support tickets per day per IP
• Crash reports: 100 crash reports per day per IP

When Limit is Exceeded:

For bug reports, feature requests, and support tickets:

HTTP Status: 403 Forbidden
Response: { "error": "Not allowed to [action]." }

For crash reports:

HTTP Status: 429 Too Many Requests

Using Project Auth Tokens

Authentication Format:

curl -H "Authorization: FormUser tkn-YOUR_TOKEN_HERE" \
     -H "BetaHub-Project-ID: pr-YOUR_PROJECT_ID" \
     -H "Content-Type: application/json" \
     https://app.betahub.io/projects/pr-YOUR_PROJECT_ID/issues.json

Creating a Bug Report:

curl -X POST \
  -H "Authorization: FormUser tkn-abc123def456..." \
  -H "BetaHub-Project-ID: pr-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Player falls through floor in level 3",
    "description": "When jumping near the water fountain...",
    "category": "bug",
    "priority": "high"
  }' \
  https://app.betahub.io/projects/pr-abc123/issues.json

Optional: Submission Tokens (JWT)

You can attach a server-generated JWT to embed trusted data (email, custom fields) that players cannot tamper with:

Authorization: FormUser tkn-YOUR_TOKEN,YOUR_JWT_TOKEN

See Submission Tokens (JWT) below for full details on generating and using these tokens.

Managing Project Auth Tokens

Viewing Tokens: In Settings → Integrations → Auth Tokens, you can see:

• Token name and creation date
• Configured permissions
• Rate limit settings
• Partial token value (first 8 characters)

Editing Tokens:

• Update token name
• Modify permissions
• Adjust rate limits
• Changes take effect immediately

Deleting Tokens:

1. Click Delete next to the token
2. Confirm deletion
3. Token is immediately revoked
4. Applications using it will receive 403 errors

Common Use Cases

Unity Plugin Integration:

// Configure BetaHub reporter
BugReportUI.projectId = "pr-abc123";
BugReportUI.authToken = "tkn-YOUR_TOKEN_HERE";

Custom Web Form:

// Submit bug from custom form
await fetch('https://app.betahub.io/projects/pr-123/issues.json', {
  method: 'POST',
  headers: {
    'Authorization': 'FormUser tkn-YOUR_TOKEN',
    'BetaHub-Project-ID': 'pr-123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: bugTitle,
    description: bugDescription,
    category: 'bug'
  })
});

Unreal Engine Crash Reporting:

; In your project's Config/DefaultEngine.ini
[CrashReportClient]
DataRouterUrl="https://app.betahub.io/crashes/unreal/tkn-YOUR_TOKEN_HERE"

Enable the “Can report crash” permission on the token. See Unreal Engine Crash Reporting for full setup instructions.

Game Launcher: Use Project Auth Tokens to allow players to submit feedback directly from your launcher without web authentication.

Submission Tokens (JWT)

When your game collects data server-side that you don’t want players to tamper with — like their email address, platform, or build number — you can use Submission Tokens. These are signed JWT tokens that your server generates through the BetaHub API, then passes to the game client. When the client submits a bug report, the token’s data is applied automatically and cannot be modified.

How It Works

1. Your server requests a submission token from BetaHub (authenticated with your Personal Access Token)
2. Your server embeds the token in the page or game client
3. The player submits a bug report — the token is included automatically
4. BetaHub verifies the token, applies the trusted data, and creates the submission
5. The token is consumed — it cannot be reused

Enabling the Requirement

By default, submission tokens are optional. To require them for a specific auth token:

1. Go to Settings → Integrations → Auth Tokens
2. Edit the token you want to protect
3. Under Security, check “Require Submission Token”
4. Save

When enabled, any submission using this auth token without a valid JWT will be rejected with a 403 Forbidden error.

Generating a Submission Token

Call the BetaHub API from your server using a Personal Access Token with developer access to the project:

curl -X POST \
  -H "Authorization: Bearer pat-YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "player@example.com",
    "custom": {
      "platform": "windows",
      "build_number": "2024.3.1"
    }
  }' \
  https://app.betahub.io/projects/pr-YOUR_PROJECT_ID/submission_tokens.json

Response (HTTP 201 Created):

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_at": "2026-03-27T16:00:00Z"
}

Parameters:

Using Submission Tokens in Submissions

Include the JWT in the Authorization header, appended to the auth token with a comma:

curl -X POST \
  -H "Authorization: FormUser tkn-YOUR_TOKEN,eyJhbGciOiJIUzI1NiJ9..." \
  -H "BetaHub-Project-ID: pr-YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": {
      "description": "The player reported a rendering glitch on the main menu."
    }
  }' \
  https://app.betahub.io/projects/pr-YOUR_PROJECT_ID/issues.json

The email and custom fields from the JWT are applied automatically. If the player’s form submission includes conflicting custom field values, the JWT values take priority.

What Data Can Be Embedded

Email: Sets the reporter identity. BetaHub creates or finds a virtual user with this email, so all submissions from the same email are linked.

Custom Fields: Any custom fields defined on your project can be set via the JWT using their field identifier. This is useful for data your server knows but the player shouldn’t control:

• Platform and OS version
• Build number or game version
• Player ID or account tier
• Region or server name

Token Rules

• Single-use: Each token can only be used for one submission. Generate a new one for each form load.
• Expiration: Tokens expire after the configured duration (default: 24 hours). Expired tokens are rejected.
• Project-scoped: A token generated for one project cannot be used to submit to a different project.

Error Messages

If a submission is rejected, the response includes a clear error message:

Security Best Practices

Token Distribution:

• ✅ Embed in game builds for in-game reporting
• ✅ Use in public-facing forms with rate limits
• ✅ Include in launcher applications
• ❌ Don’t expose tokens with high rate limits publicly
• ❌ Don’t share tokens across unrelated projects

Limit Configuration:

• Set conservative limits for public-facing tokens
• Use higher limits for trusted internal tools
• Monitor token usage through project analytics

Regular Maintenance:

• Review active tokens periodically
• Delete tokens for discontinued features
• Rotate tokens for long-running integrations
• Create separate tokens for different integrations

https://app.betahub.io/projects/pr-abc123
                               └─────┬──────┘
                                 Project ID

See Also

• Personal Access Tokens – General API access and automation
• HTML Widget – Embed feedback forms in web games
• Game Engines – Unity and Unreal Engine plugins
• Roblox Integration – In-game feedback for Roblox
• Security – Authentication and access control