Authentication
Greyhound uses GitHub tokens to authenticate API requests and verify repository permissions. There are three ways to authenticate depending on how you interact with greyhound.
CLI
The greyhound CLI uses GitHub's device authorization flow. Run:
greyhound auth login
This opens a URL where you enter a one-time code to authorize greyhound. Once authenticated, your token is stored locally in ~/.greyhound/config.json and included automatically in all CLI requests.
Tokens expire after approximately 8 hours and are refreshed automatically — you should rarely need to log in again.
Check your current auth state with:
greyhound auth status
API
API requests require an Authorization header with a GitHub token:
curl -X POST https://greyhound-api.prod.underdog.tools/api/v1/environments \
-H "Authorization: Bearer <your-github-token>" \
-H "Content-Type: application/json" \
-d '{"repository": "Underdog-Inc/api", "ref": "main"}'
Supported token types
| Token type | Format | How to get it |
|---|---|---|
| GitHub personal access token (classic) | ghp_... | GitHub Settings > Developer settings > Personal access tokens |
| GitHub fine-grained PAT | github_pat_... | GitHub Settings > Developer settings > Fine-grained tokens |
| GitHub App installation token | ghs_... | Generated by GitHub Actions via ${{ secrets.GITHUB_TOKEN }} or the GitHub API |
Required permissions
- Read endpoints (list, inspect): read (pull) access to the target repository
- Write endpoints (create, deploy, delete): write (push) access to the target repository
For personal access tokens, the repo scope covers both. For fine-grained tokens, grant Contents: Read (for read endpoints) or Contents: Read and write (for write endpoints) on the target repository.
Web UI
The web UI authenticates via GitHub OAuth. When you visit the greyhound web UI, you are automatically redirected to GitHub to log in. After authorizing, you are redirected back to the UI with an active session.
Error responses
| Status | Meaning | Resolution |
|---|---|---|
| 401 Unauthorized | No token provided or token is invalid | Include a valid Authorization: Bearer <token> header, or run greyhound auth login for the CLI |
| 403 Forbidden | Token is valid but lacks permission for the target repository | Ensure your token has access to the repository referenced in the request |
| 503 Service Unavailable | GitHub API is unreachable for token validation | Retry after a short delay |