Cloud Authentication

Authenticate with Postbase Cloud using GitHub OAuth.

Overview

Postbase uses GitHub OAuth with the device flow for CLI authentication:

1. Run postbase cloud login
2. Open the provided URL in your browser
3. Enter the verification code
4. Authorize the Postbase application
5. CLI receives access token

Login Process

Step 1: Start Authentication

postbase cloud login

Output:

Authenticating with Postbase Cloud...
 
Open this URL in your browser:
  https://github.com/login/device
 
Enter this code: ABCD-1234
 
Waiting for authorization... (press Ctrl+C to cancel)

Step 2: Enter Code

1. Open https://github.com/login/device
2. Enter the code shown in terminal (e.g., ABCD-1234)
3. Click "Continue"

Step 3: Authorize

1. Review the permissions requested
2. Click "Authorize postbase"
3. CLI automatically completes

Step 4: Confirmation

✓ Authenticated as username
 
Welcome to Postbase Cloud!
Run 'postbase cloud projects list' to get started.

Permissions

Postbase requests minimal GitHub permissions:

We do not request access to your repositories or organizations.

Token Storage

Access tokens are stored locally:

~/.postbase/cloud.json

This file contains:

{
  "access_token": "pb_xxx...",
  "user": {
    "id": "user_xxx",
    "login": "username",
    "email": "user@example.com"
  }
}

Logout

Clear stored credentials:

postbase cloud logout

✓ Logged out from Postbase Cloud

This removes ~/.postbase/cloud.json.

Check Current User

View your authenticated account:

postbase cloud whoami

Logged in as: username
Email: user@example.com
User ID: user_xxx

Token Refresh

Tokens are long-lived and don't expire automatically. If you need a fresh token:

postbase cloud logout
postbase cloud login

Programmatic Access

Using the Token

const token = process.env.POSTBASE_TOKEN
 
const response = await fetch('https://api.postbase.sh/projects', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

Environment Variables

Set POSTBASE_TOKEN for CI/CD:

export POSTBASE_TOKEN="pb_xxx..."
 
# CLI will use this token instead of stored credentials
postbase cloud projects list

CI/CD Integration

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
      
      - name: Install Postbase CLI
        run: npm install -g postbase
      
      - name: Run Migrations
        env:
          POSTBASE_TOKEN: ${{ secrets.POSTBASE_TOKEN }}
        run: |
          postbase cloud migrate up \
            -p my-project \
            -d production

Getting a Token for CI

1. Log in locally: postbase cloud login
2. Copy token from ~/.postbase/cloud.json
3. Add as secret in your CI platform

Multiple Accounts

Currently, Postbase supports one account at a time. Switch accounts by logging out and in:

postbase cloud logout
postbase cloud login  # Log in with different GitHub account

Troubleshooting

Login Stuck

If the CLI is waiting forever:

1. Check browser completed authorization
2. Try refreshing the GitHub page
3. Press Ctrl+C and retry

Invalid Token

If you see 401 Unauthorized:

# Re-authenticate
postbase cloud logout
postbase cloud login

Token Missing

If credentials file is missing:

# Re-authenticate to create new file
postbase cloud login

GitHub OAuth Error

If GitHub shows an error:

1. Ensure you're logged into GitHub
2. Try a different browser
3. Clear browser cookies for github.com
4. Contact support if persistent