Skip to content
Pullminder Docs

Authentication

The Pullminder API uses session-based authentication via GitHub OAuth. This is a cookie-based system designed for browser clients (the dashboard). The API does not issue API tokens for direct use.

GitHub OAuth flow

Section titled “GitHub OAuth flow”

The authentication flow works as follows:

  1. Initiate login — Direct the user to GET /auth/github. Pullminder redirects to GitHub’s OAuth authorization page.
  2. GitHub callback — After the user authorizes, GitHub redirects back to GET /auth/github/callback with an authorization code. Pullminder exchanges the code for an access token and creates a session.
  3. Session cookie — Pullminder sets an HTTP-only session cookie on the response. All subsequent API requests must include this cookie.

No manual token handling is required when using the dashboard. The browser stores and sends the session cookie automatically.

Checking the current session

Section titled “Checking the current session”

To verify that a session is active and retrieve the authenticated user:

GET /auth/me

Returns the current user’s profile (GitHub username, avatar, email) and the organizations they belong to. If the session is invalid or expired, the response is 401 Unauthorized.

Logging out

Section titled “Logging out”

To end the current session:

POST /auth/logout

This invalidates the session cookie. The user must re-authenticate via the GitHub OAuth flow to access the API again.

Authentication for the CLI

Section titled “Authentication for the CLI”

The Pullminder CLI does not use session-based auth. For platform commands that require authentication (such as syncing results with the dashboard), the CLI uses a GITHUB_TOKEN environment variable. See the CLI installation guide for details.

Key points

Section titled “Key points”
  • The API is session-based, not token-based. There are no API keys or bearer tokens.
  • Session cookies are HTTP-only and secure. They cannot be read by client-side JavaScript.
  • All API endpoints except /auth/github, /auth/github/callback, /health, /badge/{token}, and /webhooks/github require an active session.
  • Sessions are scoped to the authenticated GitHub user. Organization access is determined by the user’s GitHub organization memberships.

Next steps

Section titled “Next steps”
  • API endpoints — complete reference for all REST endpoints
  • Webhooks — GitHub webhook integration details