How to use API key secrets in Haystack

API keys often grant billable access to hosted models and data services, so application code should identify where a credential comes from without containing the credential itself. An environment-backed Haystack Secret gives a component that separation while keeping the pipeline serializable.

The Secret.from_env_var() method stores an environment-variable policy rather than its resolved value. The default strict behavior raises an error when the named variable is absent, while a configured process resolves the key only when the component needs it.

The OpenAIChatGenerator component already recognizes OPENAI_API_KEY by default, but passing an explicit Secret makes the credential source visible in the component configuration. Serializing the pipeline without contacting OpenAI checks disclosure behavior without consuming API requests.

1. Read the provider key into a non-echoing shell variable.

   $ read -rsp "OpenAI API key: " OPENAI_API_KEY

   The prompt keeps the key off the screen, but the shell still holds it in memory. A deployment secret manager is the appropriate credential source for a service, container, or CI job.

2. Export OPENAI_API_KEY for the Python process started from the same shell.

   $ export OPENAI_API_KEY

3. Create the environment-backed Secret in secret_use_api_key.py.

   secret_use_api_key.py

   from haystack import Pipeline
   from haystack.components.generators.chat import OpenAIChatGenerator
   from haystack.utils import Secret
    
    
   api_key = Secret.from_env_var("OPENAI_API_KEY")

4. Append the OpenAIChatGenerator initialization to secret_use_api_key.py.

   generator = OpenAIChatGenerator(model="gpt-4o-mini", api_key=api_key)

5. Append the pipeline serialization check to secret_use_api_key.py.

   pipeline = Pipeline()
   pipeline.add_component("llm", generator)
   serialized = pipeline.dumps()
    
   assert "OPENAI_API_KEY" in serialized
   assert api_key.resolve_value() not in serialized
   print(serialized)

   The assertions stop execution if the saved policy omits the variable name or exposes the resolved key value.

6. Run the completed script from the shell that exported OPENAI_API_KEY.

   $ python secret_use_api_key.py
   components:
     llm:
       init_parameters:
         api_base_url: null
         api_key:
           env_vars:
           - OPENAI_API_KEY
           strict: true
           type: env_var
         generation_kwargs: {}
         http_client_kwargs: null
         max_retries: null
         model: gpt-4o-mini
         organization: null
         streaming_callback: null
         timeout: null
         tools: null
         tools_strict: false
       type: haystack.components.generators.chat.openai.OpenAIChatGenerator
   connection_type_validation: true
   connections: []
   max_runs_per_component: 100
   metadata: {}

   The serialized YAML should contain OPENAI_API_KEY under env_vars and must not contain the provider key entered at the prompt. A secret-pattern scan can catch unrelated custom fields before a larger pipeline is shared.
   Tool: Secret Pattern Sample Checker