# Security and data handling

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

Canonical guide: <https://api.blackpearl.com/docs/security-data>

Raw Markdown: <https://api.blackpearl.com/docs/raw/security-data.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

## 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](https://api.blackpearl.com/docs/authentication) for the lifecycle and [Roles and API-key authority](https://api.blackpearl.com/docs/rbac) 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](https://api.blackpearl.com/docs/troubleshooting) to prepare a support-safe diagnostic package.