AI agent implementation prompt
Copy a complete prompt for implementing Qentrah partner OAuth, env setup, and Workspace API reads.
Use this page when you want a coding agent to wire Qentrah into a partner product. The prompt keeps the integration server-first: browser code starts OAuth, while token exchange, token storage, and Workspace API calls stay on your backend.
AI agent starter
Copy a complete implementation brief
Paste this into your coding agent to build the OAuth button, PKCE routes, server-side token exchange, env usage, and Workspace API reads.
Preview prompt
You are implementing a Qentrah partner integration in an existing web app.
Goal:
- Add organization-level OAuth with Qentrah.
- Keep all token exchange, token refresh, and token storage on the server.
- Add a frontend button with the exact copy: "Authorize with Qentrah".
- After authorization, call Qentrah Workspace partner APIs for organization, clients, and properties.
Use these existing environment variables:
- QENTRAH_WORKSPACE_API_URL: Qentrah Workspace base URL, for example http://localhost:3000 locally or the hosted Qentrah workspace URL in production
- QENTRAH_CLIENT_ID: approved OAuth client id from Qentrah Partners
- QENTRAH_CLIENT_SECRET: optional; use only for confidential server apps
- PARTNER_APP_URL: public URL of this partner app
- SESSION_SECRET: at least 32 characters if this app stores an encrypted session cookie
OAuth requirements:
- Use OAuth 2.1 authorization code flow with PKCE.
- Generate a random state value and PKCE verifier on the server.
- Store state and verifier in HttpOnly, SameSite=Lax, short-lived cookies or an equivalent server session.
- Redirect users to {QENTRAH_WORKSPACE_API_URL}/oauth/authorize with:
- response_type=code
- client_id={QENTRAH_CLIENT_ID}
- redirect_uri={PARTNER_APP_URL}/api/auth/qentrah/callback
- scope=organization:read client:read property:read offline_access
- resource={QENTRAH_WORKSPACE_API_URL}/api/v1/partner
- state=<random state>
- code_challenge=<S256 challenge>
- code_challenge_method=S256
- In the callback route, validate state before exchanging the code.
- Exchange the code on the backend at {QENTRAH_WORKSPACE_API_URL}/oauth/token with:
- grant_type=authorization_code
- client_id={QENTRAH_CLIENT_ID}
- client_secret={QENTRAH_CLIENT_SECRET}, only when present
- redirect_uri={PARTNER_APP_URL}/api/auth/qentrah/callback
- code=<authorization code>
- code_verifier=<stored PKCE verifier>
- resource={QENTRAH_WORKSPACE_API_URL}/api/v1/partner
- Require tokens.organization_id in the token response.
Frontend:
- Add an accessible button or link labeled "Authorize with Qentrah".
- The button should navigate to the server route that starts OAuth, for example /api/auth/qentrah/start.
- Do not expose access tokens, refresh tokens, client secrets, or authorization codes to browser JavaScript.
Backend Workspace API client:
- Store tokens server-side, keyed by organization_id.
- Send access tokens only in backend Authorization headers.
- Call:
- GET {QENTRAH_WORKSPACE_API_URL}/api/v1/partner/organizations/{organizationId}/me
- GET {QENTRAH_WORKSPACE_API_URL}/api/v1/partner/organizations/{organizationId}/clients
- GET {QENTRAH_WORKSPACE_API_URL}/api/v1/partner/organizations/{organizationId}/properties
- Parse Workspace errors and handle these codes in product UI where possible:
- missing_bearer
- wrong_organization
- app_not_approved
- connection_not_found
- connection_expired
- scope_denied
Security rules:
- Never place Qentrah access tokens in localStorage, query params, browser logs, or client-rendered payloads.
- Never expose QENTRAH_CLIENT_SECRET to the browser.
- Request the smallest useful scope set for the feature.
- If refresh tokens are used, rotate/store them in a durable backend token vault or database.
Acceptance criteria:
- A user can click "Authorize with Qentrah", consent in Qentrah, and return to the partner app.
- The backend stores the organization id and tokens server-side.
- The app can load organization, clients, and properties through Workspace APIs.
- Missing/expired connection states prompt the user to authorize or reconnect.
- Typecheck and build pass.Environment variables
Use the existing Qentrah partner env names. Do not rename these unless your app already has an env mapping layer.
QENTRAH_WORKSPACE_API_URL=https://your-qentrah-workspace-host.example
QENTRAH_CLIENT_ID=partners_client_...
QENTRAH_CLIENT_SECRET=
PARTNER_APP_URL=https://partner.example.com
SESSION_SECRET=replace-with-at-least-32-charactersQENTRAH_WORKSPACE_API_URL is the Qentrah Workspace base URL. Use http://localhost:3000 for local development when the workspace app is running locally, and use the hosted workspace URL for production.
QENTRAH_CLIENT_SECRET is optional for public PKCE clients. Leave it empty unless the app is a confidential server-side client.
What the agent should build
- A frontend
Authorize with Qentrahbutton that starts OAuth through a backend route. - A PKCE start route that creates state, verifier, and S256 challenge.
- A callback route that validates state and exchanges the code server-side.
- Server-side token storage keyed by the returned
organization_id. - Backend calls to Workspace partner resources for organization, clients, and properties.
Security notes
Never put Qentrah access tokens, refresh tokens, client secrets, or authorization codes in browser storage, query params, client logs, or client-rendered JSON. Partner apps should request the smallest useful scope set and reconnect users when Workspace returns connection_expired or connection_not_found.