Skip to main content

Authentication

Squawk supports two authentication methods: browser-based login (for human supervisors) and API key (for agents and CI/CD).

Browser Login (Firebase PKCE)​

Designed for human supervisors using Squawk interactively.

squawk login

This opens your default browser to a sign-in page. After you sign in, the CLI captures the OAuth callback on localhost:8089 and securely stores your credentials in the OS keychain.

What happens:

  1. Squawk generates a PKCE code verifier and challenge (SHA256, base64url)
  2. Starts a temporary HTTP server on localhost:8089 to capture the callback
  3. Opens your browser to the auth URL
  4. You sign in — the provider redirects back to localhost:8089/callback with an auth code
  5. Squawk exchanges the code for an ID token + refresh token
  6. Tokens are stored in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager)
  7. The temporary server shuts down

Required environment variables:

export FIREBASE_API_KEY=your-firebase-web-api-key
export FIREBASE_CLIENT_ID=your-oauth-client-id

Contact your Squawkpipe administrator if you don't have these values.

API Key (for Agents and CI/CD)​

Designed for automated use: AI agents, GitHub Actions, scripts.

squawk api-key
# Enter API key: (hidden input)

The key is validated against the API and stored in the OS keychain. API keys take priority over Firebase tokens — if both are stored, the API key is used.

Non-interactive (CI/CD):

# Store the key during environment setup, then use squawk normally
echo "$SQUAWK_API_KEY" | squawk api-key --tenant "$SQUAWK_TENANT_ID"

Token Refresh​

Firebase ID tokens expire after 1 hour. Squawk handles this automatically:

  1. Before each API request, the interceptor checks if the stored token is within 30 seconds of expiry
  2. If it is, Squawk calls Firebase's token refresh endpoint with the stored refresh token
  3. The new ID token is stored in the keychain
  4. The request proceeds with the fresh token

Refresh tokens are long-lived (weeks to months). If revoked (e.g., password change), you'll see:

Error: token refresh failed — run 'squawk login' again

Credential Storage​

PlatformStorage
macOSKeychain (encrypted, user-scoped)
LinuxSecret Service via libsecret (GNOME Keyring, KDE Wallet)
WindowsWindows Credential Manager

Credentials are never written to config files, environment variables, or git-tracked files.

Removing Credentials​

squawk logout

Removes all stored items: ID token, refresh token, API key, tenant ID, and expiry.

Troubleshooting​

"squawk login" hangs / browser doesn't open​

The CLI waits up to 2 minutes for the browser callback. If the browser doesn't open automatically:

  1. Copy the URL printed to stderr
  2. Paste it into your browser manually
  3. Complete the sign-in flow

If the callback server can't start on port 8089, Squawk tries ports 8090–8098.

"token refresh failed — run 'squawk login' again"​

Your refresh token has been revoked. Common causes: password change, account suspended, session invalidated.

squawk logout
squawk login

Keyring access on headless Linux servers​

On headless servers without a desktop session, libsecret may not be available.

Option 1: Use an API key (recommended):

squawk api-key

Option 2: Install and start a keyring daemon:

apt-get install gnome-keyring
eval $(gnome-keyring-daemon --start --components=secrets)