Authentication

SessionsCopy Anchor Link

The dashboard signs people in with email and password, Google or GitHub (all under /auth). A successful sign-in sets one cookie:

Set-Cookie: __Host-coderhelm_session=<token>; HttpOnly; Secure; SameSite=Strict; Path=/

Every route under /api requires it. The session lasts 7 days and slides: once it is more than halfway through, the next request gets a fresh cookie with your current role. Someone removed from the team gets no fresh cookie, so their access ends with the session.

Because the cookie is SameSite=Strict and the API only accepts cross-origin requests from the dashboard, a page on another site can't use your session.

A request without a valid session gets 401.

TeamsCopy Anchor Link

A person can belong to several teams. The session holds the current team, and every request acts on it; there is no team header. To switch:

POST /api/teams/switch
Content-Type: application/json

{ "team_id": "<team id>" }

CoderHelm checks you are a member, then sets a new cookie for that team. GET /api/teams lists your teams.

RolesCopy Anchor Link

Each route checks a capability against your role in the current team, on the server. A member calling an admin-only route gets 403.

Streaming tokensCopy Anchor Link

Plan chat streams its answer from stream.coderhelm.com, which can't read the session cookie. The dashboard first asks for a short-lived token:

POST /api/plans/chat/token

{ "token": "<token>" }

The token is valid for 5 minutes and is sent as a bearer token:

POST /api/plans/chat/stream
Authorization: Bearer <token>

CI uploadsCopy Anchor Link

CoderHelm reads test reports from your GitHub workflow runs by itself. A CI job whose results never reach GitHub (a device farm, say) can upload its report instead, signed with GitHub Actions' own OIDC identity token, so you don't store a CoderHelm secret in CI. Request a token with the audience coderhelm and send the report file as the body:

permissions:
  id-token: write
  contents: read
steps:
  - name: Upload test results to CoderHelm
    run: |
      TOKEN=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
        "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=coderhelm" | jq -r .value)
      curl -sS -X POST "https://api.coderhelm.com/webhooks/ci/tests/results?name=results.json" \
        -H "Authorization: Bearer $TOKEN" \
        --data-binary @test-results/results.json

• name is the report's file name and must end in .json (Playwright or Cucumber JSON) or .xml (JUnit XML). One report of at most 6 MB per request.
• CoderHelm checks the token was issued by GitHub for one run of a repository connected to your team, with E2E results turned on under Tests.
• The same token can ask which tests are quarantined: GET /webhooks/ci/tests/quarantine.

Two-factor sign-inCopy Anchor Link

People can turn on two-factor authentication under Security. Sign-in then asks for a code (POST /auth/mfa/verify) before the session cookie is set.