Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Generate API Keys

API keys let you connect external applications to Haystack Enterprise Platform. You need them to use API endpoints or when working in an SDK. You can create API keys at the workspace or organization level with different roles and permissions.

About This Task​

API keys authenticate your applications when making requests to the Haystack Enterprise Platform API. Each key has:

  • Scope: workspace or organization. Keys generated for a workspace grant access only to this specific workspace. Keys generated for an organization grant access to all workspaces in the organization.
  • Type: personal or service. Personal keys are tied to your user account. Service keys are for automated systems. They're not linked to a specific user. Instead of a username, the search history will show the key name as the actor. Use this type for production applications or systems that connect to Haystack Enterprise Platform.
  • Role: Determines what actions the key can perform. You can't grant the key more permissions than you already have.
  • Expiration: Optional expiration date for security.
info

API keys can't be used to create, modify, or delete other API tokens. This prevents unauthorized expansion of access.

Role Restrictions​

When creating an API key, you cannot grant the key more permissions than you already have:

  • Organization role: Only organization admins can create a token with the organization Admin role. If you are a member and request an Admin organization role for the token, the request fails with a 403 error.
  • Workspace role: The workspace role assigned to the token cannot exceed your own role in that workspace. For example, if you hold the Editor role in a workspace, you cannot create a token with the Admin role for that workspace.
  • Custom roles: Custom roles and default roles are incompatible. If you hold a custom role in a workspace, you can only create a token with that exact same custom role — not with any default role (External, Search User, Editor, or Admin), and not with a different custom role. Similarly, if you hold a default role, you cannot create a token with a custom role.

Organization admins are exempt from workspace-level role checks and can create tokens with any role.

Security and Best Practices​

  • Use service keys for automated systems and production environments
  • Set expiration dates for keys used in temporary or testing scenarios
  • Regularly review and remove unused API keys
  • Store API keys securely and never commit them to version control
  • Use workspace-scoped keys when possible to limit access
  • Give your keys meaningful names so that you can easily identify them in the search history and audit logs

Prerequisites​

Learn about available roles and their permissions to choose the right one for your key. Check User Roles and Permissions.

Generate an API Key from the UI​

For a Workspace​

  1. Click your profile icon in the top right corner and choose Settings.
  2. Go to Workspace>API Keys.
  3. Click Create API Key:
    1. Choose if it's a personal or a service key.
      Tip: Choose the Service type for production use cases and systems that connect to Haystack Platform.
    2. Give your key a name. This is optional, if you don't type any name, the key ID is used. It's recommended to give your keys a meaningful name so that you can easily identify them in the search history and audit logs.
    3. Set the expiration date.
    4. Choose the role to determine the key's permissions.
  4. Click Create API Key.
  5. Important: Copy and save your key. After you add it to Haystack Enterprise Platform, it remains masked.

For an Organization​

  1. Click your profile icon in the top right corner and choose Settings.
  2. Go to Organization>API Keys.
  3. Click Create API Key:
    1. Choose if it's a personal or a service key.
      Tip: Choose the Service type for production use cases and systems that connect to Haystack Platform.
    2. Give your key a name. This is optional, if you don't type any name, the key ID is used. It's recommended to give your keys a meaningful name and description so that you can easily identify them in the search history and audit logs.
    3. Set the expiration date.
    4. Choose the workspaces this key can access.
    5. Choose the role to determine the key's permissions.
  4. Click Create API Key.
  5. Important: Copy and save your key. After you add it to Haystack Enterprise Platform, it remains masked.