# Integrate Zorveus into this project: Developer OAuth

## What Zorveus does and the selected route

Zorveus routes AI requests to supported model providers, records usage, and applies funding and spending policies. This integration uses Developer OAuth: users authorize this tool to make inference requests against their own Zorveus funding context. It is not a Business integration where this product funds customer inference.

Read https://docs.zorveus.com/llms.txt and follow the source Markdown links. Start with /getting-started/oauth-app-quickstart and the /oauth guides. Use current official documentation and the installed SDK to verify contracts. Do not invent routes, scopes, token lifetimes, refresh tokens, request fields, or model availability.

## Inspect and implement

Inspect authentication, account linking, providers, clients, all AI calls, background jobs, secrets, errors, streaming, cancellation, and tests. Inventory the paths to integrate. Reuse existing client interfaces and configuration. Explain the plan before substantial changes and obey repository approval rules. Implement supported paths, retain unsupported paths, and report gaps. Do not ask questions the repository or official docs can answer.

Preserve existing OpenAI Chat Completions, Responses, Anthropic Messages, TypeSafe System One, embeddings, and media request shapes where supported. Use async clients on async paths. Do not force every modality through chat or add separate vendor clients solely for Zorveus. Preserve tools, structured results, streaming, retries, normalization, and dimension handling.

Ask the owner to select models at https://www.zorveus.com/models when necessary. Verify the selected models against the authorized token's model policy. Use https://api.zorveus.com/v1 for OpenAI-compatible clients and the documented endpoint and authentication for other protocols. TypeSafe uses https://api.zorveus.com/typesafe. Do not silently substitute models.

## Register the app in the dashboard

Create or select a Developer organization in https://app.zorveus.com and register the OAuth app there. Configure exact redirect URIs for each environment, minimum required scopes, selected models, test users, and consent spending policies. Confirm current dashboard labels and publication requirements in the docs. Give the operator a checklist; never ask them to paste secrets into chat.

Choose a confidential or public client based on the host application's security boundary. A confidential backend stores the client secret server-side. A public client does not embed a client secret. Both use Authorization Code with PKCE. Do not create apps, connections, caps, provider credentials, or webhook settings through service-key calls.

Use the project's settings conventions. Typical settings are ZORVEUS_CLIENT_ID, ZORVEUS_REDIRECT_URI, and ZORVEUS_CLIENT_SECRET for confidential clients only. Store authorized user tokens in the existing protected credential store, not one global environment variable.

## Implement authorization and account linking

1. Start from an authenticated local user or the application's existing trusted account-linking flow.
2. Generate unpredictable state and a PKCE verifier and S256 challenge. Bind state and verifier to the initiating session, with a short expiry and one-time consumption.
3. Direct the user to the documented /oauth/authorize endpoint with client_id, exact redirect_uri, requested scopes, state, and PKCE fields. Follow the current authorization-request and consent contracts.
4. Handle denied consent and callback errors. Validate state, its session binding, expiry, and one-time use before exchanging a code. Do not let one account attach another account's authorization.
5. Exchange the single-use code through form-encoded POST /oauth/token. Include grant_type=authorization_code, client_id, code, code_verifier, and the same redirect_uri. Confidential clients include client_secret; public clients omit it.
6. Store the returned access token against the local user with ownership checks and protected storage. Redact codes, verifiers, tokens, and secrets from logs. Verify response fields against the current SDK or docs.

The access_token is a scoped inference credential with the zrv_ prefix. Use it for that user's model calls. Never use the OAuth client secret as an inference key. Do not invent a refresh-token flow; implement documented reauthorization behavior when necessary.

## Use the correct user's token

Resolve the authorized token at a trusted account boundary. Preserve the local user identity through workers and scheduled work so they can retrieve the correct credential. Do not put plaintext tokens in durable job payloads when the existing secret store can resolve them by ID.

Do not mutate a shared client's token between users. Use isolated clients or documented request-scoped authorization. Test concurrent calls from two users. Do not fall back silently to a Business inference key when a user's authorization fails.

OAuth authorization establishes the connection and funding context. Do not import the Business product-user attribution, credit-grant, or allowance-anchor workflow into OAuth. User OAuth connections use enforce, and inference requests cannot change a product-user allowance anchor. Follow the documented OAuth behavior rather than assuming Business headers apply.

## Handle limits, disconnection, and revocation

Use documented structured errors. Distinguish revoked or invalid authorization, model-policy denial, allowance exhaustion, insufficient funding, and transient provider failures. Never label every 403 as an exhausted user. Preserve bounded transient retries; do not repeatedly retry confirmed funding or policy failures.

Return clear application errors and terminal stream events. Show reconnect or funding guidance where appropriate. Do not leave a message or media job appearing to process forever. Keep application decision and public response contracts independent of model choice.

For disconnect, use form-encoded POST /oauth/revoke with token and client_id. Confidential clients also use client_secret; public clients omit it. Follow current error and retry behavior. Remove local credentials after confirmed revocation, including an already-revoked result. Track uncertain failures rather than claiming remote access was revoked. Reconnection starts a new authorization flow.

This route does not require a Business service key, plan-to-inference-key mapping, customer credit grants, or Stripe fulfillment. Preserve the host application's existing billing. Do not add a new billing system or grant credits merely because Zorveus supports them. If organization webhooks are explicitly in scope, configure them in the dashboard and follow signature, replay, app-scoping, and durable acceptance guidance.

## Verify and hand off

Test successful authorization, denied consent, invalid or replayed state, expired state, incorrect PKCE, exact redirect matching, token exchange failure, cross-user isolation, concurrent inference, revoked tokens, disconnect retries, and reauthorization. Test each AI path in scope and preserved streaming, tools, typed outputs, and background work. Never log real tokens or make live credentials required for unit tests.

Run the repository formatter and affected tests. Give a review guide explaining authorization, credential ownership, one inference request, and disconnection. List changed files, dashboard setup, settings names without values, supported and unchanged AI paths, tests, and remaining gaps. Do not claim completion for uninspected or untested paths.