Token Guide: Coder Auth & API Token

For OAuth App creation, see Token Guide: OAuth App.

Wire the OAuth App into Coder external auth

Coder external auth is a first-class feature that stores a per-user GitHub token inside the Coder control plane and exposes it to Coder Agents through the Chats API. OpenFlows does not manage this token directly; it relies on Coder to attach the correct identity to each agent request.

Add the external auth provider in Coder

1. Log in to your Coder deployment as an administrator and navigate to Admin → External auth → Add provider.
2. Select GitHub as the provider type.
3. Paste the Client ID and Client secret from the OAuth App you created.
4. Set the Authorization callback URL to exactly the value registered in the OAuth App. Coder will show you this URL; copy it back to GitHub if it differs.
5. Save the provider. Coder will display the provider ID, which you will reference when adding a tenant.

Tenant authorization

When you run the tenant add command, OpenFlows asks Coder to link the repository to a Coder user via the configured external auth provider. The tenant owner must authenticate with GitHub and approve the requested scopes. After that, every agent action for that tenant uses the token stored in Coder.

# Add a tenant and link GitHub through Coder external auth
./scripts/prod.sh tenant owner/repo --name my-team

The command does not ask for a GitHub token. It asks Coder to resolve the identity, and Coder completes the OAuth exchange. The token is stored in the Coder control plane, never in the OpenFlows database or in a worker workspace.

Obtain the Coder API token

The OpenFlows orchestrator is a Coder user with a long-lived API token. It needs this token to provision workspaces, query templates, read user details, and send messages to the Coder Chats API. The token is stored in the orchestrator environment as CODER_SESSION_TOKEN.

Create a dedicated Coder user

Do not use your own Coder user account for the orchestrator. Create a dedicated user such as openflows-orchestrator, assign it the appropriate roles, and issue the API token under that user. This keeps audit logs unambiguous and lets you revoke the token without disabling a human account.

Generate the token

1. Log in to Coder as the orchestrator user.
2. Go to User settings → Tokens → New token.
3. Give the token a clear name, such as openflows-orchestrator-prod.
4. Select the scopes required for the orchestrator:
   • Workspaces - create, read, update, and delete ephemeral worker workspaces.
   • Templates - read templates so OpenFlows can pick the correct role-specific template.
   • Users - read user and organization metadata for tenant mapping.
   • Organizations - read organization membership when using org-scoped templates.
5. Copy the token and store it in your secret manager. Coder shows it only once.

Set the token in the environment

Open .env in the OpenFlows repository and add the token. If you are running in a container orchestrator, mount the token as a secret instead of putting it in an image or environment variable in version control.

# .env
CODER_URL=https://coder.example.com
CODER_SESSION_TOKEN=coder_token_...