API Access

Secure programmatic access to BetaHub through authentication tokens and RESTful API endpoints.

Authentication Methods Overview

BetaHub provides two types of authentication tokens designed for different use cases:

Personal Access Tokens

For: General API access, automation scripts, CI/CD pipelines Prefix: pat- Created by: Individual users in their account settings Scope: Full access to all projects the user can access Rate Limiting: None Authentication: Authorization: Bearer pat-YOUR_TOKEN_HERE

Best for:

• Custom integrations and scripts
• CI/CD pipeline automation
• Third-party application development
• Administrative tasks across multiple projects

→ Jump to Personal Access Tokens section

Project API Tokens

For: In-game bug reporting, game launchers, project-specific tools Prefix: tkn- Created by: Project owners in project settings Scope: Single project with configurable permissions Rate Limiting: Configurable IP-based limits (default: 8 requests/day per IP) Authentication: Authorization: FormUser tkn-YOUR_TOKEN_HERE

Best for:

• In-game bug reporting (Unity, Unreal Engine plugins)
• Game launcher integrations
• Project-specific embedded forms
• Limited public access to specific project features

→ Jump to Project API Tokens section

Personal Access Tokens

Personal Access Tokens provide secure authentication for API requests without exposing your login credentials.

What Are Personal Access Tokens?

Personal Access Tokens act as an alternative authentication method that gives you the same level of access as your regular account, but are designed for:

• API integrations with external systems
• Third-party applications that need BetaHub access
• Automated scripts for workflow automation
• CI/CD pipelines for deployment integration

Creating Your First Token

Step 1: Navigate to Token Management

1. Click on your profile picture in the top right corner
2. Select “Profile & Account” from the dropdown menu
3. On the Profile page, locate the “API Access” card
4. Click the “Manage API Tokens” button
5. View your existing tokens (if any) with names, creation dates, and partial values

Step 2: Create a New Token

1. Click the “New Token” button
2. Fill in the required information:
   • Token Name (required): Descriptive name for identification
     • Good examples: “API Integration”, “CI/CD Pipeline”, “Production Scripts”
   • Expiration Date (optional): When the token should expire

Step 3: ⚠️ CRITICAL: One-Time Token Display

Token Management

Viewing Existing Tokens

In your Personal Access Tokens page, you can see:

• Token Name - The descriptive name you provided
• Creation Date - When the token was created
• Expiration Date - When it will expire (if set)
• Partial Token - First 8 characters of the token hash for identification
• Last Used - When the token was last used in an API request (or “Never” if unused)
• Actions - Delete button for each token

Deleting Tokens

To remove a token you no longer need:

1. Find the token in your list
2. Click the “Delete” button
3. Confirm the deletion

Project API Tokens

Project API 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 API Tokens are scoped to a single project with configurable permissions and rate limits.

What Are Project API Tokens?

Project API 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 API Tokens

Step 1: Navigate to Project Settings

1. Go to your project dashboard
2. Click Settings in the sidebar
3. Select API Tokens from the settings menu

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 Reports - Allow bug/issue submission
• Bug Reports Per Day - Daily limit per IP address (default: 8)

Feature Requests:

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

Releases:

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

Rate Limiting and IP Tracking

Project API 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 per day per IP
• Feature requests: 8 per day per IP

When Limit is Exceeded:

HTTP Status: 403 Forbidden
Response: { "error": "rate limit exceeded" }

Using Project API 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: User Identification with JWT

You can attach a JWT token to identify the submitter:

Authorization: FormUser tkn-YOUR_TOKEN,YOUR_JWT_TOKEN

This associates the submission with a specific user while using the token’s project permissions.

Managing Project API Tokens

Viewing Tokens: In Project Settings → API 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'
  })
});

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

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

Using Personal Access Tokens

This section covers using Personal Access Tokens (pat- prefix) for general API access. For Project API Token usage, see the Project API Tokens section above.

Authentication Method

Personal Access Tokens use Bearer token authentication:

Bearer Token Authentication:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -H "Accept: application/json" \
     https://app.betahub.io/projects.json

URL Format

API endpoints support JSON responses in two ways:

# Option 1: Using .json extension
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://app.betahub.io/projects.json

# Option 2: Using Accept header
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -H "Accept: application/json" \
     https://app.betahub.io/projects

Token Permissions

Your personal access token inherits the same permissions as your user account:

• Project Access - All projects you have access to
• Read Permissions - View issues, comments, project data
• Write Permissions - Create and modify issues, add comments
• Administrative Access - Manage projects you own or administrate

API Endpoints

Projects

List Projects:

GET /projects.json

Get Project Details:

GET /projects/{project_id}.json

Create Project:

POST /projects.json
Content-Type: application/json

{
  "name": "My Game Project",
  "description": "Game project description",
  "visibility": "public"
}

Issues (Bugs, Suggestions, Tickets)

List Issues:

GET /projects/{project_id}/issues.json

Get Issue Details:

GET /projects/{project_id}/issues/{issue_id}.json

Create Issue:

POST /projects/{project_id}/issues.json
Content-Type: application/json

{
  "title": "Bug report title",
  "description": "Detailed bug description",
  "category": "bug",
  "priority": "high"
}

Valid category values: "bug", "feature_request", "question"

Update Issue:

PATCH /projects/{project_id}/issues/{issue_id}.json
Content-Type: application/json

{
  "status": "resolved",
  "assigned_to_id": 123
}

Comments

Users and Organizations

Get Current User:

GET /profiles/me.json

Response includes your user profile with name and project roles.

Example Integrations

JavaScript/Node.js

// Example: Fetching projects using a personal access token
const response = await fetch('https://app.betahub.io/projects.json', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

const projects = await response.json();
console.log(projects);

// Create a new bug report
const newBug = await fetch('https://app.betahub.io/projects/pr-123/issues.json', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Player cannot move after level 3',
    description: 'Detailed description of the bug...',
    category: 'bug',
    priority: 'high'
  })
});

Python

import requests

# Configure headers
headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

# Get projects
response = requests.get('https://app.betahub.io/projects.json', headers=headers)
projects = response.json()

# Create issue
issue_data = {
    'title': 'Performance issue in level 5',
    'description': 'Game freezes when entering level 5...',
    'category': 'bug',
    'priority': 'medium'
}

response = requests.post(
    'https://app.betahub.io/projects/pr-123/issues.json',
    headers=headers,
    json=issue_data
)

Environment Variable Setup

# Set in your environment
export BETAHUB_TOKEN="your_token_here"

# Use in scripts
curl -H "Authorization: Bearer $BETAHUB_TOKEN" \
     -H "Accept: application/json" \
     https://app.betahub.io/projects.json

Security Best Practices

Token Creation

Use Descriptive Names:

• ✅ Good: “Production API Integration”, “Development Scripts”
• ❌ Bad: “Token1”, “Test”, “My Token”

Set Expiration Dates:

• Use shorter expiration periods for better security
• Consider your integration’s needs when setting dates
• You can always create new tokens when needed

Create Separate Tokens:

• Don’t share tokens across multiple integrations
• Use different tokens for different environments
• Makes access management and revocation easier

Token Storage

Secure Storage Methods:

• Use environment variables, not hardcoded values
• Encrypt tokens when storing them
• Use secure credential managers in production

Never Share Publicly:

• Don’t commit tokens to code repositories
• Don’t include tokens in screenshots or documentation
• Don’t share tokens in chat applications or emails

Regular Maintenance

Review and Cleanup:

• Delete unused tokens regularly
• Review token list periodically
• Remove tokens for discontinued integrations
• Replace tokens that may have been compromised

Troubleshooting

Common Issues

Token Not Working:

1. Verify token hasn’t expired
2. Check Authorization header format: Bearer YOUR_TOKEN
3. Ensure Accept: application/json header is included
4. Verify account permissions for the resource

Lost Token:

1. There’s no way to recover lost tokens
2. Delete the old token from your list
3. Create a new token with the same name
4. Update all applications using the old token

API Errors

Authentication Errors (401):

• Token is invalid, expired, or malformed
• Missing or incorrect Authorization header
• Token has been deleted

Authorization Errors (403):

• Token is valid but lacks permission for the resource
• Account doesn’t have access to the requested project

Validation Errors (422):

• Request data failed validation
• Missing required fields
• Invalid field values

Error Response Format: All API errors return JSON in this format:

{
  "error": "Error message describing the issue"
}

Advanced Usage

Webhook Integration

Combine API access with webhooks for real-time updates:

1. Configure webhooks to receive notifications
2. Use API to fetch detailed information
3. Process updates automatically in your system

CI/CD Integration

Example GitHub Actions workflow:

name: Sync Issues to BetaHub
on:
  issues:
    types: [opened, closed]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Create BetaHub Issue
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.BETAHUB_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"title":"${{ github.event.issue.title }}","description":"${{ github.event.issue.body }}"}' \
            https://app.betahub.io/projects/pr-123/issues.json

Custom Dashboard Creation

Use the API to build custom analytics and reporting:

// Fetch project metrics
const issues = await fetch('/projects/pr-123/issues.json').then(r => r.json());
const openBugs = issues.filter(i => i.category === 'bug' && i.status === 'open');
const resolvedThisWeek = issues.filter(i => 
  new Date(i.resolved_at) > Date.now() - 7 * 24 * 60 * 60 * 1000
);

// Create custom visualizations
console.log(`Open bugs: ${openBugs.length}`);
console.log(`Resolved this week: ${resolvedThisWeek.length}`);

Getting Help

Support Resources

Documentation:

• API reference documentation - Complete endpoint documentation
• Integration examples and tutorials
• Best practices guides

Community Support:

• Join our Discord server for help
• Share integration examples with the community
• Get help from other developers

Direct Support:

• Contact support for complex integration issues
• Enterprise customers get priority API support
• Report API bugs and feature requests

Common Questions

Q: How many tokens can I create? A: There’s no strict limit, but we recommend creating only the tokens you need for security.

Q: Do tokens expire automatically? A: Only if you set an expiration date. Tokens without expiration remain valid indefinitely.

Q: Will changing my password affect my tokens? A: No, personal access tokens work independently of your password.

Q: Can I see which applications are using my tokens? A: Currently, token usage tracking is limited. This feature is planned for future releases.

Next Steps

• Integrations - Explore built-in integration options
• Organizations - Manage team access and billing
• Project Settings - Configure advanced project features