Security and data handling
Review credential boundaries, project isolation, capability data flow, retention, and logging behavior.
Credential boundary#
Public API keys are project-scoped secrets. The console displays a new secret once; the gateway stores only its hash for later authentication. Keep the key in a server-side secret manager, inject it into the calling process at runtime, and send it only in the Authorization: Bearer ... header over HTTPS. Never commit it, put it in a URL, paste it into a support request, or embed it in browser, desktop, or mobile code where an end user can extract it.
Rotate without downtime by creating a replacement key in the same project, deploying it to every server-side caller, confirming traffic on the replacement, and then revoking the old key. Revocation and configured expiry stop new authentication immediately. The platform's private capability-service credentials remain at the gateway and are not returned to API clients or forwarded from the client's Bearer key.
Tenant and ownership boundaries#
Authentication resolves one organization and one project from the key. Public campaign and job operations enforce that project boundary: an ID owned by another project is returned as 404 not_found, including when the caller knows the ID. Usage is attributed to the key's project, while matching organization-, project-, key-, and capability-scoped controls can govern new work.
Use separate projects and keys for development, staging, production, or customers whose jobs and accounting must be isolated. A key is not a user session and does not inherit console membership roles. See Authentication and project environments for the lifecycle and Roles and API-key authority for the authorization model.
Data sent for capability work#
The gateway stores the validated public input and sends the fields needed to the configured private capability service:
| Capability | Data sent upstream | Data returned and retained by the platform |
|---|---|---|
| Playbooks | Target company name or domain, anchor-company and product context, requested tone/sections, a job correlation value, and the selected brand profile's branding snapshot when present. | Generated account research, personas, sales guidance, attributed usage, and private backend correlation diagnostics. |
| Audiences | Campaign name and objective, website/product/ICP/additional context, target size and workflow settings, excluded domains, reusable campaign setup artifacts, and organization/job correlation values. | Candidate summary, candidate pages fetched from the capability service, reusable setup artifacts, delivered-domain deduplication data, stage state, usage, cost, and private backend correlation diagnostics. |
| Message Templates | Template generation sends the validated audience, objective, offer summary, desired next step, copy controls, and selected Brand/Offer/Campaign snapshots to OpenAI Responses with provider storage disabled. Prospect personalization sends no prospect identity, work email, retained evidence, sender identity, or compliance data to OpenAI; it verifies platform ledgers and renders the selected immutable revision locally. | Immutable structural revisions, generation input/result, OpenAI token/cost attribution and private response correlation IDs, plus personalization inputs and approval artifacts. Personalization job data can include prospect and sender identity, work email, retained evidence references, and compliance attestations/verifications. |
Do not submit secrets or regulated personal data in free-text targeting, product, or additional-context fields unless your agreement explicitly permits it. Candidate output can include business contact data; apply your own access, lawful-use, export, and deletion controls after retrieval. The platform uses separately configured service credentials for upstream calls—your project API key is not sent to capability services.
Retention and deletion#
Every public job publishes expires_at, exactly 30 days after creation. Until then, the gateway exposes owned job metadata, input, result, and Audience candidates. Client timeout does not cancel execution; retain the job ID and resume polling. Store any result your application must keep beyond expires_at in a system with your required security and deletion policy.
Message personalization refuses a Prospecting source job as soon as its expires_at boundary is reached, both when accepting the request and again before execution. This prevents a queued job from reusing prospect PII after the source retention window closes.
After expiry, public job and candidate reads return 410 job_expired. Scheduled cleanup removes the platform-retained job input, result, error detail, stages, and private job diagnostics, while keeping a minimal ownership/status tombstone. Append-only usage, downstream cost, credit, and audit ledgers remain for accounting and security requirements. The 30-day gateway cleanup is not a promise that a configured upstream capability service has deleted its own operational records; upstream deletion obligations are governed by the applicable service agreement.
Logs, errors, and request IDs#
The gateway request log records request ID, method, path, status, latency, and client IP. It does not write the Authorization header, query string, or request/response body in that log. Public errors replace unexpected internal failures with a stable safe message. Usage and audit records can store request correlation metadata, principal IDs, operation names, status, and accounting values; job payload and private backend diagnostics are retained as described above.
Send a valid X-Request-ID to correlate a call, or use the generated ID returned in the X-Request-ID response header and error.request_id. A request ID is not a secret, but it must never be used as a substitute for authentication. Follow Troubleshooting and request diagnostics to prepare a support-safe diagnostic package.