Secrets and Integrations
Add secrets and integration to safely connect Haystack Enterprise Platform to model and service providers.
Overview
Secrets and integrations let you connect Haystack Enterprise Platform to external models or services. These connections allow your pipeline components to use those services without including the API key directly in the component's configuration.
Scope
You can add secrets and integrations at the workspace or organization level
- Workspace-level connections are available only to pipelines and indexes within that specific workspace.
- Organization-level connections are available to all workspaces in the organization.
- Service-level secrets are available only to one service. For details, see Service-Level Secrets.
If the same provider is connected at both the workspace and organization level, the workspace-level connection takes priority and is used in pipelines and indexes.
If you delete a workspace-level connection, but the same provider is connected at the organization level, the organization-level connection is used automatically.
Service-Level Secrets
You can also add a secret to a single service. Only that service can use it, and it doesn't appear in the workspace or organization secrets lists. Use service secrets when one service needs its own credentials, for example a production key that other services in the workspace shouldn't use.
If secrets with the same name exist at more than one level, a service uses the one with the highest priority. From lowest to highest priority:
- Organization secret
- Workspace secret
- Service secret
If you delete a service secret, the service uses the workspace or organization secret with the same name, if one exists.
Service secrets apply to services that run in serverless mode. Managed services don't use them yet. Service secrets are also used when the platform reads a service's tool schema for the MCP server. When you delete a service, its secrets are deleted with it.
To add a service secret, see Add Secrets to a Service.
How Do They Work
Each secret or integration sets an environment variable to store the API key. This way, pipeline components can access the key without you having to add it manually to the configuration. The API key is read from the environment variable.
Integrations
Integrations are most frequently used connections You can find them under Integrations in Workspace and Organization settings.
To connect to a listed provider, just enter your API key and any required details. The platform fills in the integration name for you.
Currently, on the Connections page you can set up connections with the following model providers:
- Amazon Bedrock
- Azure OpenAI
- Cohere
- Google AI
- Hugging Face (only needed for private models hosted there)
- MongoDB
- NVIDIA
- OpenAI
- SearchAPI
- Together AI
- Voyage AI
- Weights & Biases
Supported connections to data processing services and data sources are:
- Azure AI Document Intelligence
- DeepL
- Snowflake
- Unstructured
Secrets
Secrets let you connect to providers not listed on the Integrations page. Use them to:
- Securely manage provider credentials required for custom components to authenticate without hard coding them in pipeline YAMLs.
- Manage different provider credentials for development and production environments.
You can create multiple secrets for one provider, such as one for a development key and another for a production key. This makes it possible to easily swap keys in the pipeline configuration.
Secrets store credentials for third-party providers, such as OpenAI, Cohere, AWS, or Anthropic. If you need a key to call the deepset API itself, see Generate API Keys instead.
For Existing Components
If you're using an existing component (like LangfuseConnector), check its documentation to learn the correct name for the secret. The component reads the API key from a specific environment variable, so the secret name must match that variable name.
For Custom Components
If you're building a custom component, make sure your code uses an environment variable to get the API key. Then, use that variable name as the secret name in the platform.
User OAuth Tokens in Pipelines
To let a pipeline component call a third-party service, such as Google Drive or Slack, on behalf of the person who runs it, use that person's OAuth token instead of one shared credential. The token is the access token issued by an OAuth provider your admin registered. Components read the token from an environment variable, like any secret, for example with Secret.from_env_var("<ENV_VAR_NAME>").
How the Token Gets to a Pipeline
When a pipeline runs, the platform adds an environment variable for each OAuth provider that has an environment variable name and that the user has connected to. For pipeline configurations, the platform adds only the variables the pipeline references. The variable name is the Environment Variable Name of the provider, which the admin sets when registering it. The default is USER_CONNECTION_ followed by the provider type. The value is the user's current access token. For how admins set the name, see Configure External Connections.
If a user's connection can't be refreshed, the platform skips it. The run continues without that variable, so a component that needs the token must handle a missing value. If a component fails because the token is missing, ask the user to reconnect the provider, then run the pipeline again.
Who Receives a Token
The platform adds tokens only when a run represents one person:
- A user signed in through single sign-on (SSO).
- A request made with that user's personal API key.
Shared credentials never receive tokens: service API keys, shared prototype links, shared jobs, and background deployment runs such as scheduled runs and Slack. These runs act for a stand-in user, so their tokens aren't passed on.
Secret Names
A secret can't use the environment variable name of an OAuth provider, and you can't rename a secret to one. This prevents a secret from overriding a user's token.
Limits
- Tokens are passed only to pipelines that run in serverless mode.
- A run that lasts longer than the access token's lifetime can't refresh the token during the run.
Was this page helpful?