# Connect Velocity reference service

Node.js 20+; no dependencies. This separate service runs on a loopback port and exchanges OAuth codes as a confidential server or public PKCE client.

Download [server.mjs](https://docs.velocity.quest/examples/oauth-service/server.mjs) from the public Docs site, or use this directory in a source checkout. The script is self-contained; no repository access or SDK installation is needed.

1. As an admin/owner, register an **External service** in Velocity → Settings → OAuth Apps. Register `http://127.0.0.1:8787/callback` and `read:issues write:issues read:teams read:workspaces`. The publisher workspace can differ from all customer workspaces.
2. Set `VELOCITY_CLIENT_ID` and, for a confidential client, `VELOCITY_CLIENT_SECRET` in your shell via your secret manager. Do not commit credentials. Public clients omit the secret. `PORT` optionally changes the loopback port; `VELOCITY_URL` defaults to `https://velocity.quest`.
3. For a downloaded copy, run `node server.mjs` in its directory. From a source checkout, run `node examples/oauth-service/server.mjs`. Open the printed local URL and click **Connect Velocity**. Sign in as a customer and explicitly select workspaces.
4. The service displays identity and the approved workspaces. To create a test issue, select one and provide its team UUID and a title. Find team IDs with `query($workspaceId:ID!){teams(workspaceId:$workspaceId){id name}}` at `/api/graphql`, using the same token and `X-Workspace-Slug`.
5. Refresh and disconnect with the form buttons. Scope/workspace/role restrictions are enforced by Velocity. Refresh failure requires new consent; do not reuse an old public refresh token. User revocation in Velocity invalidates this service too.

To read issues from the service, use its `api(session, '/api/v1/issues', {headers:{'X-Workspace-Slug':slug}})` helper. The [full API contract](https://docs.velocity.quest/api/oauth) includes cursor pagination, issue updates, deletion and GraphQL capabilities.

This is a local demonstration, not an Internet-ready customer service: sessions and credentials live only in process memory, loopback HTTP cookies omit Secure, and callback state expires after five minutes. Restarting requires consent again. For production, add your own customer authentication, HTTPS with Secure HttpOnly SameSite cookies, durable encrypted per-customer credential storage, bounded session storage and distributed refresh locking. Keep browser-bound state, PKCE, issuer verification, Origin/CSRF checks and output escaping. Do not expose tokens to browsers or log authorization requests. Register a new client and revoke/delete the old client to replace a confidential secret.
