Secure OpenAI Structured Extraction: Keys, Logs, Permissions, and Rotation
A practical security workflow for extracting structured data with OpenAI: isolate credentials, restrict permissions, validate JSON output, redact logs, and rotate keys safely.
Summary · TL;DR
For structured extraction, keep the OpenAI application key in a trusted application layer, not in agent-generated code or logs. Request schema-constrained output, validate it again in your application, and treat validation failures as recoverable errors rather than trusted data. Separate credentials by purpose, redact sensitive content from logs, and document a rotation and revocation procedure.
Key Takeaways
- Keep the application API key outside agent or sandbox environments; give each workload only the access it needs.
- A JSON schema constrains output format, but application-side validation and business-rule checks are still necessary.
- Log request identifiers and validation outcomes where useful, not raw credentials or sensitive extracted text.
- Maintain a written key-rotation procedure that covers deployment, verification, and immediate revocation after suspected exposure.
On this page (7)
The safe pattern for structured extraction
For extracting fields from documents, separate the job into three parts: a trusted application sends the request, the model returns schema-shaped data, and your application validates and decides what to store or act on. Keep credentials in the trusted application layer. Do not put the application key into prompts, generated code, container images, or logs.
OpenAI’s sandbox security guidance says agent-generated code can access files, credentials, and network resources available to its environment. It recommends isolated workloads, restricted network access, separate credentials, and keeping the application API key outside the environment. It also says to rotate or revoke keys when needed. See OpenAI’s sandbox security guidance.
The examples below are illustrative, not tested against a live account. Check the current API documentation for the endpoint and parameter support in your chosen SDK or provider. Do not assume that a compatible API endpoint supports every OpenAI parameter.
Prerequisites and trust boundaries
Before implementing extraction, identify where each piece of data and credential lives:
- Application: holds the OpenAI application key and makes the model request.
- Model or sandbox environment: receives only the task data and tools it needs; it should not receive the application key.
- Logs and monitoring: record operational metadata without retaining secrets or unnecessary document content.
- Storage or downstream actions: accept extracted values only after schema and business-rule checks.
Use a dedicated project or credential for the application or workload where practical. Restrict permissions to the API actions it needs. OpenAI’s guidance lists api.responses.write for inference and, for its Agents API sessions, api.agents.read and api.agents.write; vault management additionally requires vault permissions. These are specific to the documented functions, not a universal permission recipe. Grant only the scopes relevant to your implementation.
Request schema-shaped data, then validate it
Define the output fields and their types before writing the extraction prompt. For example, a receipt workflow might require a merchant name, date, currency, and total. The following schema is illustrative; adapt required fields and formats to your data and the API’s currently supported schema subset.
{
"type": "object",
"properties": {
"merchant": { "type": "string" },
"date": { "type": "string" },
"currency": { "type": "string" },
"total": { "type": "number" }
},
"required": ["merchant", "date", "currency", "total"],
"additionalProperties": false
}
Configure the request to use a JSON-schema output mode if the selected endpoint supports it. Keep the prompt focused on extraction, and tell the model to represent unavailable information according to a defined policy rather than inventing a value. If missing fields are allowed, encode that explicitly in the schema and downstream handling.
Schema-constrained output is not a substitute for validation. Parse the response as JSON, validate it against the schema in your application, and apply domain checks—for example, that the date is parseable and the total is non-negative. Reject or quarantine invalid results instead of silently converting them into trusted records. Preserve the original document only where your retention policy permits it.
Redact logs without losing diagnostics
Avoid logging API keys, authorization headers, full prompts, complete model responses, or raw documents by default. Extracted fields can themselves contain personal or confidential information, so logging the “successful” JSON response may still create a sensitive-data store.
Useful lower-risk diagnostics can include a request correlation ID, timestamp, model identifier, outcome category, validation pass or fail, and latency. If you need examples for debugging, use synthetic or deliberately redacted inputs and apply access controls and retention limits. Ensure exceptions do not serialize request headers or response bodies automatically.
For structured extraction, record which field failed validation rather than its sensitive value. Keep access to any retained source document separate from operational logs, and define who can view it and how long it is retained.
Rotate and revoke credentials deliberately
Write the rotation procedure before an incident. A practical procedure should specify who can create and deploy a replacement key, where it is stored, how dependent services are updated, how the new key is verified, and how the old key is revoked. If the credential may have been exposed, prioritize revocation and containment over waiting for a routine rotation window.
Store long-lived credentials in a secrets manager. OpenAI’s guidance warns that injecting a stored secret into an environment still exposes it to agent-generated code. For hosted sandboxes, it describes using vault secrets through a proxy for approved hosts; for self-hosted environments, it recommends a trusted proxy or server that supplies secrets outside the environment. For function tools, keep credentials in the application handling the call and return only the result.
After rotation, check that the application uses the new credential and that the old one no longer works. Review access logs and deployment history for unexpected use, and update incident records if exposure was suspected. Do not copy keys into tickets or chat while coordinating the change.
Common failures and responses
- The output is valid JSON but contains a wrong value: JSON validity proves structure, not factual accuracy. Add field-level business checks and a review path for consequential decisions.
- A required field is absent or malformed: treat it as a failed extraction; retry only under a bounded policy or send it for review.
- A key appears in a log or sandbox: revoke it, replace it through the documented process, and investigate where it was exposed.
- A request fails after changing providers or endpoints: verify documented support for the endpoint and schema parameters. OpenAI-compatible access does not by itself establish identical feature support.
A compact pre-release checklist
- Application key is held outside agent-generated code and sandbox environments.
- Credentials are scoped and separated by workload or purpose where practical.
- Network access is limited to approved destinations.
- Schema, parsing, and business-rule validation are implemented.
- Logs exclude keys, raw documents, and unnecessary extracted values.
- Rotation, verification, and emergency revocation steps have an owner.
- Provider and endpoint support for the chosen structured-output parameters has been confirmed.
Secure structured extraction depends on the whole path, not just the response format: protect the credential, minimize what reaches logs and environments, validate every result, and make revocation straightforward.
FAQ
Does JSON schema validation guarantee that extracted data is correct?
No. A schema can constrain the shape and types of a response, but it cannot establish that a value matches the source document. Parse and validate the response in your application, then add domain-specific checks and human review where the consequences warrant it.
Should an OpenAI API key be available inside an agent sandbox?
Avoid exposing the application key to agent-generated code. OpenAI’s sandbox security guidance says such code can access credentials available to its environment and recommends keeping the application API key outside it. Use a trusted application layer or a suitable credential-brokering design instead.
What should an extraction service log?
Prefer operational metadata such as a correlation ID, outcome category, and validation status. Do not log keys, authorization headers, full prompts, raw documents, or complete extracted records by default.
When should a key be revoked rather than rotated on schedule?
Revoke it promptly if you suspect exposure, such as finding it in a log, source file, image, or environment accessible to untrusted code. Then deploy a replacement through your approved process and investigate the exposure.
Related articles
Guides
Secure OpenAI API Keys in a Document-Q&A Workflow
A practical security pattern for OpenAI document question answering: separate credentials, restrict permissions, redact logs, and rotate keys safely while preserving source attribution.
Guides
Grok Imagine Image API Cost Estimate for a JSON Extraction Workflow
Estimate image-generation charges for Grok Imagine Image, identify missing extraction costs, and validate structured records against a JSON schema.
Guides
Qwen4 Max API Cost Guide for JSON Schema Extraction
Estimate Qwen4 Max extraction costs per document and per 100,000 documents, including retries, cache assumptions, and JSON schema validation.
Guides
GPT Image 2 API costs for structured extraction: an assumption-driven estimate
Estimate GPT Image 2 workload costs using explicit token assumptions, and understand why JSON extraction support must be verified before budgeting a production workflow.