OAuth Server Setup

Create and rotate OAuth applications in the dashboard, and set the correct redirect URL for hosted vs self-hosted flows.

3 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Start for $0

Overview

OpenQuok supports OAuth applications so third-party services (or infrastructure you operate) can run the OAuth2 authorization code flow and receive opo_ tokens for programmatic access.

OAuth apps vs workspace programmatic token

This page covers third-party apps under Developers → Apps (client ID oqc_). For automation in your own workspace — scripts, CI, or rotating a personal token — use Developers → Access instead. See Public API authentication.

Only workspace admins can manage OAuth apps for their workspace. The client secret is shown only once (when you create the app or rotate it).

Create an OAuth app (dashboard)

Open developer settings

In the OpenQuok web app, go to:

Account → Settings → Developers → Apps

Create the app

Click Create OAuth app and fill:

App name — label shown on the consent screen
Description — optional
Redirect URL — see the next section (this is the critical part)

After creating, copy:

Client ID (prefix oqc_...)
Client secret (prefix oqs_...) — shown once

Store the secret in your server-side secret manager / env, not in the browser or a repo.

Redirect URL: hosted vs self-hosted

The redirect URL must match the server that will receive the OAuth callback.

Hosted CLI device flow (OpenQuok-operated)

OpenQuok production splits the device flow:

CLI API: https://cli-auth.openquok.com (SERVER_URL)
Browser: https://www.openquok.com/cli/device/verify and callback below

Create the OAuth app with this redirect URL:

https://www.openquok.com/cli/device/callback

Then set the auth server env vars:

OPENQUOK_OAUTH_CLIENT_ID
OPENQUOK_OAUTH_CLIENT_SECRET
SERVER_URL=https://cli-auth.openquok.com
BROWSER_ORIGIN=https://www.openquok.com

Also set CLI_AUTH_SERVER_URL=https://cli-auth.openquok.com on the web Vercel project. These belong in server env (synced from agent/server/.env.production.local and web/.env.production.local), not in the CLI.

CLI users do not need the secret

CLI users run openquok auth:login and never see the OAuth client secret. The secret lives only on the auth server.

Self-hosted auth server (customer-operated)

If a customer self-hosts their own auth server, they must create an OAuth app with:

SERVER_URL/device/callback

Where SERVER_URL is the public HTTPS origin of their auth server (no trailing slash).

For the auth server configuration details, see Configuration - Agent.

Redirect URL examples (self-hosted)

Production (split web + API, recommended):

https://your-web.example.com/cli/device/callback

Production (single host — browser and API on same origin):

https://auth.example.com/device/callback

Local development (auth server only, default):

http://localhost:3111/device/callback

Rotation and safety notes

Rotating the client secret will require updating whatever server uses it.
Changing backend SECURITY_SECRET invalidates existing OAuth secrets/tokens; see Security secrets.

Public API authentication

Workspace programmatic tokens (opo_) vs third-party OAuth apps

OAuth2 for third-party apps

Authorization code flow for apps you build for other users

Configuration - Agent

CLI auth server env vars and callback URL

Security secrets

SECURITY_SECRET and what it invalidates