Token & Authentication Guide

OpenFlows is a thin orchestration brain that runs on top of a self-hosted Coder deployment. Coder is the only runtime. Every GitHub action, every workspace provision, and every LLM call is routed through Coder's governed control plane. Tokens are therefore the single most sensitive part of the deployment: they are the boundary between the autonomous agents and the repositories, infrastructure, and model providers they touch.

This guide explains how to obtain and configure the three credentials OpenFlows needs: a GitHub OAuth App for Coder external authentication, a Coder API token for the orchestrator, and - in test environments only - a GitHub personal access token. It also covers the required scopes, rotation procedures, and security controls that keep the deployment safe.

Worker workspaces contain zero credentials

Coder workspaces created for FORGE, SENTINEL, VESSEL, and LORE workers contain no AI software, no LLM keys, and no GitHub tokens. The Coder Agent runs in the Coder control plane and reaches into the workspace through the same secure tunnel that an IDE uses. All GitHub identity is resolved by Coder external auth; orchestration commands are issued through the Coder Chats API.

What you are configuring

A production OpenFlows deployment needs exactly two long-lived secrets in the orchestrator's environment, plus one short-lived per-user OAuth flow that Coder manages for the tenant:

GitHub OAuth App - registered in GitHub and wired into Coder external auth. This is how Coder obtains a short-lived, scoped token to act on GitHub as the tenant. It is the only production path for GitHub authentication.
Coder API token (CODER_SESSION_TOKEN) - issued to the OpenFlows orchestrator so it can call the Coder control plane, provision workspaces, and dispatch Chats API messages.
GitHub PAT (test only) - in isolated test environments, a personal access token may be placed at /tmp/github_token. It is a convenience for integration tests and is never used in production.

No other token is required. Do not put GitHub PATs, LLM API keys, or cloud credentials inside worker workspaces, and do not store them in repository code. The entire credential model is centralized in Coder or the orchestrator host.

Register a GitHub OAuth App

The GitHub OAuth App is the production source of identity. OpenFlows does not accept PATs in production, so every tenant repository must be reachable through a Coder-managed OAuth session that is backed by this app.

Create the OAuth App

Open Settings → Developer settings → OAuth Apps in your GitHub account or organization. If the repository is owned by an organization, create the app under the organization so it can be authorized at the org level.
Click New OAuth App and fill in the fields:
- Application name: a descriptive name such as OpenFlows - Coder External Auth.
- Homepage URL: the root URL of your Coder deployment, e.g. https://coder.example.com.
- Authorization callback URL: the Coder external auth callback endpoint. For a default Coder deployment this is https://coder.example.com/external-auth/callback. The exact path is shown in the Coder dashboard when you add the external auth provider.
Uncheck Enable Device Flow unless you have a specific use case for it; OpenFlows uses the web-based authorization flow.
Click Register application. On the next page, click Generate a new client secret and copy both the client ID and the client secret to a password manager or vault. GitHub will show the secret only once.

Select the scopes

OAuth App scopes are requested by Coder when the tenant authorizes the connection. Request the smallest set that still lets the autonomous team read the repository, open pull requests, and merge them. The recommended scopes are:

Scope	Why it is needed
repo	Full read and write access to the target repository. FORGE needs this to read code, push branches, and open pull requests. VESSEL needs this to poll merge status and perform the merge.
workflow	Grants permission to read and update GitHub Actions workflow files. Enable only if the repository contains workflows that the agents may modify or extend.
read:org	Read-only access to organization membership. Required when the target repository is owned by a GitHub organization, because Coder external auth must resolve the organization-scoped identity.
user:email	Read-only access to the authenticated user's email addresses. Coder uses this to map the GitHub identity to a Coder user account.

Use a dedicated OAuth App per environment

Register one GitHub OAuth App for production, another for staging, and a separate one for local development. This isolates scopes, audit logs, and blast radius if a client secret is leaked. Never reuse the production OAuth App for ephemeral test tenants.

Authorize the organization

If the target repository belongs to an organization, the OAuth App must be authorized at the organization level before Coder can request tokens on behalf of members. A user can authorize the app for their own account, but the organization authorization is what grants access to organization-owned repositories.

Go to Organization settings → Third-party access → OAuth Apps, find the app you created, and click Grant access. Members will then see the app during the Coder external auth flow and can approve it for their own accounts.

See Coder External Auth & API Token for wiring the OAuth App into Coder and obtaining the orchestrator token.