API Authentication | FlightStack

API authentication

FlightStack uses GitHub OAuth to issue user tokens, and a separate per-machine token system for build agents.

Endpoints

Method	Path	Auth	Purpose
POST	/authentication/github-login	None	Complete the OAuth code exchange and issue tokens.
POST	/authentication/refresh-token	None (refresh in body)	Refresh an expired access token.
POST	/authentication/logout	Bearer	Invalidate the current refresh token.
GET	/authentication/me	Bearer	Get the authenticated user’s profile.
GET	/github/oauth-url	Bearer	Build the GitHub authorization URL.
POST	/github/connect	Bearer	Link a GitHub account to an existing user.

Login flow

The standard OAuth flow has three steps:

1. Build the OAuth URL — GET /github/oauth-url?redirectUri=https://your.app/cb. Returns { "authorizationUrl": "https://github.com/login/oauth/authorize?…" }. Redirect the user.
2. GitHub redirects back to your redirectUri with ?code=….
3. Exchange the code — POST /authentication/github-login:

   {
     "code": "abc123...",
     "redirectUri": "https://your.app/cb"
   }

   Returns { accessToken, refreshToken, expiresAt, user }.

For CLI logins this is wrapped in flightstack login — it spins up a tiny localhost server, opens the browser, and finishes the exchange transparently.

Using the access token

Add the Authorization header to every authenticated request:

curl https://api.flightstack.voostack.com/authentication/me \
  -H "Authorization: Bearer eyJhbG..."

Token refresh

Access tokens expire (typically 1 hour). Use the refresh token to mint a new one:

curl -X POST https://api.flightstack.voostack.com/authentication/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"eyJhbG..."}'

Returns { accessToken, refreshToken, expiresAt }. The new refresh token rotates — the old one is invalidated after a brief grace period.

Tip

The CLI does this transparently — it refreshes on every command if the token is within 60 seconds of expiry.

Logout

curl -X POST https://api.flightstack.voostack.com/authentication/logout \
  -H "Authorization: Bearer eyJhbG..."

Invalidates the refresh token. The access token still works until its natural expiry.

Current user

curl https://api.flightstack.voostack.com/authentication/me \
  -H "Authorization: Bearer eyJhbG..."

Returns the authenticated user’s profile (id, email, avatarUrl, githubUsername, organizations, …).

Connecting GitHub later

A user who signed up another way can connect a GitHub account by calling POST /github/connect with the same { code, redirectUri } payload as login.

Agent tokens

Build agents authenticate with an agent token in a different header:

curl https://api.flightstack.voostack.com/buildagent/{agentId}/poll \
  -H "Agent-Token: eyJhbG..."

The agent token is issued by POST /buildagent (agent registration) and stored on the machine at ~/.flightstack/config.json under token. It’s scoped to a single agent — losing it requires re-registering.

See Agents for the full agent endpoint surface.