Railway Authentication

Manage Railway authentication for CLI, API, and CI/CD workflows.

Overview

Railway supports multiple authentication methods for different use cases:

• Interactive Login: Browser-based OAuth for developers
• Browserless Login: Device code flow for SSH/Codespaces/headless
• API Tokens: Programmatic access for automation and CI/CD

When to Use

• Setting up Railway CLI for first time
• Authenticating in CI/CD pipelines
• Creating API tokens for automation
• Verifying authentication status
• Troubleshooting auth issues

Operations

Operation 1: Interactive Login

Standard browser-based authentication for local development.

Command:

railway login

Process:

1. Opens browser to Railway OAuth page
2. Authenticate with GitHub/email
3. CLI receives authentication token
4. Token stored in ~/.railway/config.json

Verification:

railway whoami
# Output: Logged in as: your-email@example.com

Use When: Local development, first-time setup

Operation 2: Browserless Login

Device code authentication for headless environments.

Command:

railway login --browserless

Process:

1. CLI generates device code
2. Display URL and code to user
3. User visits URL on any device
4. Enters code to authenticate
5. CLI receives token after approval

Example Output:

To authenticate, visit: https://railway.app/cli-auth
Enter code: ABCD-1234
Waiting for authentication...

Use When:

• SSH sessions
• GitHub Codespaces
• Remote servers
• Docker containers
• Any environment without browser

Operation 3: Token-Based Authentication

Use API tokens for programmatic access and CI/CD.

Token Types:

Creating Tokens:

1. Visit https://railway.com/account/tokens
2. Click "Create Token"
3. Select token type and scope
4. Copy token (shown only once!)

CLI Authentication with Token:

# For Project Tokens
export RAILWAY_TOKEN=<your-project-token>

# For Account/Team Tokens
export RAILWAY_API_TOKEN=<your-account-or-team-token>

# Verify
railway whoami

API Authentication:

# Account Token
curl -H "Authorization: Bearer $RAILWAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { me { name email } }"}' \
  https://backboard.railway.com/graphql/v2

# Project Token
curl -H "Project-Access-Token: $RAILWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { projectToken { projectId } }"}' \
  https://backboard.railway.com/graphql/v2

Use When: CI/CD pipelines, automation scripts, API integrations

Operation 4: Verify Authentication

Check current authentication status.

Commands:

# Check who you're logged in as
railway whoami

# Check current project context
railway status

# Verify token via API
curl -s -H "Authorization: Bearer $RAILWAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { me { name } }"}' \
  https://backboard.railway.com/graphql/v2

Troubleshooting Auth Issues:

CI/CD Integration

GitHub Actions

name: Deploy to Railway
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Railway CLI
        run: npm install -g @railway/cli

      - name: Deploy
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
        run: railway up --ci

Setup:

1. Create Project Token in Railway dashboard
2. Add as RAILWAY_TOKEN secret in GitHub repo settings
3. Use --ci flag for non-interactive deployment

GitLab CI

deploy:
  stage: deploy
  image: node:20
  script:
    - npm install -g @railway/cli
    - railway up --ci
  variables:
    RAILWAY_TOKEN: $RAILWAY_PROJECT_TOKEN
  only:
    - main

Token Security Best Practices

1. Never commit tokens - Use environment variables or secrets managers
2. Use minimal scope - Project tokens for single-project CI/CD
3. Rotate regularly - Delete and recreate tokens periodically
4. Monitor usage - Check Railway dashboard for unusual activity
5. Separate environments - Different tokens for dev/staging/prod

Quick Reference

References

• token-types.md - Detailed token comparison and usage
• token-troubleshooting.md - Common auth issues and fixes

Related Skills

• railway-api - GraphQL API automation
• railway-automation - CI/CD patterns
• railway-project-management - Project setup