Security and data handling

Review credential boundaries, project isolation, capability data flow, retention, and logging behavior.

Credential boundary#

Public API keys are secrets. A project key acts only in its own project; a company-level key can act in every project of your organization and, over the API, create and archive projects and change their allowances and limits, so protect it like an administrator credential. 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 of the same type (in the same project, for a project key), 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 the organization from the key and one project for each request: a project key's own project, or, for a company-level key, the project named by the Blackpearl-Project header, else the project of the job, campaign, or audience the request addresses, else the key's default project. Public campaign and job operations enforce that boundary: a project key gets 404 not_found for an ID owned by another project, including when the caller knows the ID, and a project key that names another project gets 403 forbidden. Usage and charges are attributed to the project the work ran in, while matching organization-, project-, key-, and capability-scoped controls can govern new work.

Brands and offers belong to the organization, not to a project: any of the organization's keys, including a project key, can list and read them. If you run a project per client and one client must not see another's brand names, don't give that client a project key of its own. See Managing your clients with projects.

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 console access 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:

CapabilityData sent upstreamData returned and retained by the platform
PlaybooksTarget 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.
AudiencesCampaign 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 TemplatesTemplate generation sends the validated audience, objective, offer summary, desired next step, copy controls, and selected Brand/Offer/Campaign snapshots to a third-party model provider with provider-side storage disabled. Prospect personalization sends no prospect identity, work email, retained evidence, sender identity, or compliance data to a model provider; it verifies platform ledgers and renders the selected immutable revision locally.Immutable structural revisions, generation input/result, private billing attribution and 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, billing, 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.

Hosted Infinite Intent reports#

Infinite Intent reports require a valid Blackpearl browser session and an explicit viewer grant. Other signed-in users receive 404, including project members and platform admins. Signed-out visitors sign in before returning to the page. URLs and legacy share tokens grant no access. Reports expire with job retention, use private/no-store responses, and isolate report scripts from application cookies/storage while blocking network calls.