Authentication

Game Framework supports multiple authentication methods for accessing your private packages.

Authentication Methods

1. User Tokens (Development)

For individual developers working locally.

Generate Token:

curl -X POST https://registry.yourcompany.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"your_password"}' \
  | jq -r '.token'

Configure:

export GF_PUB_TOKEN="eyJhbGciOiJIUzI1NiIs..."

# Add to ~/.pub-cache/pub-tokens.json
{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}

2. API Keys (CI/CD)

Long-lived keys for automation and CI/CD pipelines.

Create API Key:

curl -X POST https://registry.yourcompany.com/v1/workspaces/ws_YOUR_ID/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions CI",
    "description": "Key for automated publishing",
    "permissions": ["packages.read", "packages.create", "versions.create"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "id": "key_c0s6t7vjnb0c73f5g6eg",
  "key": "gf_live_abc123def456...",
  "name": "GitHub Actions CI"
}

Save this key immediately! It cannot be retrieved later.

Use in CI/CD:

# GitHub Actions
env:
  GF_PUB_TOKEN: ${{ secrets.GAME_FRAMEWORK_TOKEN }}
  
# GitLab CI
variables:
  GF_PUB_TOKEN: $GAME_FRAMEWORK_TOKEN

3. OAuth (Coming Soon)

OAuth 2.0 integration for enterprise SSO.

Token Storage

Development Environment

# Add to ~/.zshrc or ~/.bashrc
export GF_PUB_TOKEN="your_token_here"

# Create pub-tokens.json
mkdir -p ~/.pub-cache
cat > ~/.pub-cache/pub-tokens.json << 'EOF'
{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}
EOF

# Add to PowerShell Profile
$env:GF_PUB_TOKEN = "your_token_here"

# Create pub-tokens.json
$pubCache = "$env:APPDATA\Pub\Cache"
New-Item -ItemType Directory -Force -Path $pubCache

@"
{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "`$env:GF_PUB_TOKEN",
      "env": "GF_PUB_TOKEN"
    }
  ]
}
"@ | Out-File -FilePath "$pubCache\pub-tokens.json" -Encoding UTF8

CI/CD Environment

Store tokens as secrets:

GitHub Actions:

Settings → Secrets → Actions → New repository secret
Name: GAME_FRAMEWORK_TOKEN
Value: Your API key

GitLab CI:

Settings → CI/CD → Variables → Add variable
Key: GAME_FRAMEWORK_TOKEN
Value: Your API key
Check "Masked" and "Protected"

Token Types

User Tokens

Lifetime: 24 hours (configurable)
Scope: All workspace permissions for user
Use case: Local development
Renewal: Re-login when expired

API Keys

Lifetime: Custom (up to 1 year)
Scope: Specific permissions
Use case: CI/CD, automation
Renewal: Create new key before expiration

Permissions

API keys can have specific permissions:

{
  "permissions": [
    "packages.read",      // Read package metadata
    "packages.create",    // Create new packages
    "versions.create",    // Publish versions
    "artifacts.upload",   // Upload artifacts
    "webhooks.create"     // Manage webhooks
  ]
}

Permission Scoping

Limit API keys to minimum required permissions:

# Read-only key for CI dependency resolution
{
  "permissions": ["packages.read", "versions.read"]
}

# Publishing key for release pipeline
{
  "permissions": ["packages.read", "versions.create", "artifacts.upload"]
}

Token Rotation

Regular rotation improves security:

Create New API Key

curl -X POST https://registry.yourcompany.com/v1/workspaces/ws_ID/api-keys \
  -H "Authorization: Bearer $OLD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New CI Key","permissions":["packages.read","versions.create"]}'

Update CI/CD Secrets

Update the secret in your CI/CD platform with the new key.

Verify New Key Works

Run a test build to ensure new key works.

Revoke Old Key

curl -X DELETE https://registry.yourcompany.com/v1/api-keys/key_OLD_ID \
  -H "Authorization: Bearer $NEW_TOKEN"

Security Best Practices

1. Never Commit Tokens

Add to .gitignore:

.env
.env.local
*.key
secrets/

2. Use Environment Variables

# ✗ Don't hardcode
export TOKEN="gf_live_abc123..."

# ✓ Load from secure source
export GF_PUB_TOKEN=$(cat ~/.secrets/gf_token)

3. Rotate Regularly

User tokens: Expire after 24 hours (automatic)
API keys: Rotate every 90 days (manual)

4. Minimum Permissions

Grant only necessary permissions:

# ✗ Too broad
"permissions": ["*"]

# ✓ Specific
"permissions": ["packages.read", "versions.create"]

5. Monitor Usage

Track API key usage:

curl https://registry.yourcompany.com/v1/api-keys/key_ID/usage \
  -H "Authorization: Bearer $TOKEN"

Troubleshooting

"Unauthorized" Error

Causes:

Token expired
Token not set in environment
Invalid token format
Insufficient permissions

Solutions:

# Check token is set
echo $GF_PUB_TOKEN

# Verify token format (should start with gf_live_ or gf_test_)
echo $GF_PUB_TOKEN | cut -d'_' -f1-2

# Test token
curl -H "Authorization: Bearer $GF_PUB_TOKEN" \
  https://registry.yourcompany.com/v1/me

Token Not Loading

Check pub-tokens.json:

cat ~/.pub-cache/pub-tokens.json

# Should output:
{
  "version": 1,
  "hosted": [...]
}

Verify environment variable:

# Should print your token
printenv | grep GF_PUB_TOKEN

Next Steps

CI/CD Integration - Automate with CI/CD
API Keys - Detailed API key management
Security - Security best practices

Questions? See troubleshooting or contact support.

On this page