AI Prompt Engineering

Overview

Every authenticated call to the AI service must include a valid API key and pass an authorization check at the authentication endpoint. This section documents the authentication endpoint contract and the exact headers you must send to enable secure, auditable access using the Zero-Leak Key Vault Method.

Quick Reference

Parameters

Code Example

# Use a secret manager value; never hardcode the API key.
# Example: export API_KEY from your vault at runtime.
export API_KEY="$(printenv API_KEY_FROM_VAULT)"

curl -sS -X POST "https://api.example.com/v1/authenticate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "prompt-engineering-service",
    "scope": "prompts:read prompts:write",
    "request_id": "req_01J6Z3KQX5P7S1T9A2B3C4D5"
  }'

// Node.js example using fetch. Assumes API_KEY is loaded from a server-side secret store.
import crypto from "crypto";

const API_KEY = process.env.API_KEY_FROM_VAULT; // do not log this
const AUTH_URL = "https://api.example.com/v1/authenticate";

const requestId = `req_${crypto.randomBytes(12).toString("hex")}`;

const res = await fetch(AUTH_URL, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    client_id: "prompt-engineering-service",
    scope: "prompts:read prompts:write",
    request_id: requestId,
  }),
});

if (!res.ok) {
  const err = await res.text(); // avoid printing API_KEY; redact if logging
  throw new Error(`Auth failed: HTTP ${res.status} ${err}`);
}

const data = await res.json();
// data.access_token is used to authenticate subsequent requests.
console.log("authenticated", data.access_token ? "true" : "false");

Response Format

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_at": "2026-07-28T12:34:56Z",
  "request_id": "string",
  "scope": "string"
}

Field descriptions:

• `access_token`: Short-lived token used in future `Authorization` headers (`Bearer `).
• `token_type`: Always `Bearer` for this endpoint.
• `expires_at`: ISO-8601 timestamp; client must refresh before expiry.
• `request_id`: Correlation ID to trace authentication attempts.
• `scope`: Effective scope granted by the server.

Notes & Best Practices

• Zero-Leak Key Vault Method: Keep the long-lived API key only in a server-side secret manager (AWS Secrets Manager, GCP Secret Manager, Vault). Never commit it to git, inject it into front-end bundles, or write it to logs.
• Do not confuse credentials: Use the API key for `/v1/authenticate`, then use the returned `access_token` for subsequent calls.
• Rate limits and retries: On `429 Too Many Requests`, retry with exponential backoff and respect any `Retry-After` header if present.
• Error handling: Treat `401/403` as credential/scope failures (no retries without changing inputs); treat `5xx` as transient and retry idempotent auth attempts using `request_id`.

Authentication is the gate. Once you can reliably mint an `access_token`, the next chapter can focus on how to pass authenticated context into prompt and completion endpoints without leaking secrets through logs or request payloads.