API Access

Secure programmatic access to BetaHub through Personal Access Tokens and RESTful API endpoints.

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 “Personal Access Tokens” from the dropdown menu
3. 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 - Only the last 8 characters for identification
• 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

Using Your API Token

Authentication Methods

BetaHub supports three authentication methods:

1. Bearer Token Authentication (Recommended):

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

2. FormUser Token Authentication:

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

3. Anonymous Access (for public resources):

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

URL Format

All API endpoints use the .json extension to return JSON responses:

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

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",
  "type": "bug",
  "priority": "high"
}

Update Issue:

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

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

Comments

List Comments:

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

Create Comment:

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

{
  "content": "This is a comment on the issue"
}

Users and Organizations

Get Current User:

GET /user.json

List Organizations:

GET /organizations.json

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...',
    type: '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...',
    'type': '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

Rate Limiting

Current Limits

• Standard rate limits apply per token
• Shared limits across all tokens for your account
• Burst allowance for short-term higher usage

Best Practices

Implement Exponential Backoff:

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Monitor Rate Limit Headers:

const response = await fetch(url, options);
const remaining = response.headers.get('X-RateLimit-Remaining');
const resetTime = response.headers.get('X-RateLimit-Reset');

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

Rate Limiting:

1. Implement exponential backoff in your code
2. Monitor rate limit headers in responses
3. Spread requests over time rather than batching
4. Contact support if you need higher limits

API Errors

Authentication Errors (401):

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

Authorization Errors (403):

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

Rate Limit Errors (429):

• Too many requests in a short time period
• Implement backoff and retry logic

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 $" \
            -H "Content-Type: application/json" \
            -d '{"title":"$","description":"$"}' \
            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.type === '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 (link coming soon)
• 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