Authentication
Issue scoped backend credentials and distinguish tenant access, delegation and test fixtures.
Use credentials issued by your provisioned Q environment. The public SDK default is https://api.qdivision.ai/v1; the deployment's capability registry declares which operations require a credential and their scopes. Public status/reference metadata may be anonymous. First-party and administrative APIs are not automatically available to a third-party credential.
Wocha user and developer accounts
Q's public application and developer portal use Wocha's hosted authorization-code flow with PKCE. Email login, social accounts and organisation SSO are selected in Wocha. Registration starts the hosted sign-up flow; Q does not store passwords. Organisation SSO connections, verified domains and MFA policy are configured in Wocha.
In the developer portal, create an organisation directly in Q or use an existing Wocha membership. Organisation owners and admins can issue, deactivate, reactivate and delete Q API keys. Q reads current membership and role from Wocha's Account API before these operations. An ordinary member cannot manage keys. New keys default to read, ai:chat and ai:answer; choose other capabilities explicitly. The raw key is shown only on creation.
Wocha machine credentials
A registered Wocha OAuth client can use client_credentials with audience=q-api and its granted Q scopes. Send the returned access token as a bearer credential. Its signed org_id must identify the Q organisation; Wocha's identity-platform tenant_id does not select Q data. Machine tokens cannot access developer-account or user-session endpoints.
Cross-organisation service access additionally requires a reviewed client ID in Q's WOCHA_FIRST_PARTY_CLIENT_IDS and first_party scope. A human token or an unlisted machine client does not gain that access from the scope alone. The outbound q-provisioner client is separate: it uses platform:provision to manage Wocha organisations, rather than accessing Q data.
Server-side API credentials
Send Authorization: Bearer <credential>. Q also accepts X-API-Key for API-key authentication. Keep credentials in environment variables or a secret store; never put them in a URL, source file or browser bundle. Obtain, rotate and revoke keys through the environment's administrator or configured control plane. Key issuance and commercial entitlements are deployment-specific.
The examples require Q_API_KEY and accept Q_API_BASE_URL. Python imports Q from q_client; TypeScript imports it from @getq/sdk. These examples do not automatically load a repository .env.
Tenant identity is derived from the authenticated credential. Caller-supplied tenant or user fields do not grant access. Delegating a distinct end user requires an authorised delegation scope and Q's resource-permission checks; see retrieval permissions.
Scopes and availability
| Journey | Relevant advertised scope/condition |
|---|---|
| Search | The search operation's registry policy (deployment enforcement applies) |
| Grounded answer | ai:answer |
| Embeddings | ai:embeddings |
| Sonar chat | ai:chat |
| Headless retrieval/context | ai:search; memory:read for optional owner memory |
| Headless extraction/documents/refinement | ai:generate; also ai:search for retrieval-backed input |
| Agent creation/start/status | ai:answer plus the agent_api feature |
| Acting for a different end user | identity:delegate, when permitted, plus the operation scope |
Use the registry instead of assuming that read/write, a wildcard or an internal route grants every capability. A 403 can indicate a missing scope, unavailable feature or denied resource. Examine the structured error code and correlation ID without logging the credential.
Test keys and sandbox isolation
Q recognises a q_test_ prefix and marks authenticated requests as test mode. This is not a separate tenant, a resource ACL or proof of billing/provider isolation. A key must still be issued and validated by the configured authority. Confirm tenant separation, entitlements and metering with the operator before using a real environment.
The local contract sandbox is the deterministic alternative: it binds loopback, accepts only a fixed non-secret fixture token and returns synthetic data. It never loads provider keys, calls Q or touches production data. It makes no live execution or Temporal durability claim.
Browsers
Keep Q service credentials on a backend. The React starter exchanges a local application session for a short-lived CSRF token and sends requests to a same-origin proxy. That token is meaningful only to the proxy; it is not a Q API key. The proxy chooses the Q credential and checks operation inputs and run ownership.
The starter automatically creates sessions only on its loopback development server. A production integration must authenticate the application's user, map their tenant and permitted resources server-side, issue secure sessions and enforce distributed limits. See the backend proxy contract.
Errors and retries
Missing/invalid credentials return 401; insufficient authorisation generally returns 403. Refresh or correct credentials explicitly. For other failures, use the error contract, SDK transport policy and idempotency guide. Never turn a timeout or 503 on a mutation into a fresh request with a new operation key.
Versioned extensions use explicit extensions:read, extensions:manage, extensions:use and connectors:sync scopes. Owner/grantee checks apply independently of scopes; provider credentials stay on the developer host.