Add documentation for the new tool credentials system in the vault

doc/source/admin/special_topics/vault.md

@@ -125,4 +125,49 @@ In a file source the password could be used as follows:
   password: ${user.user_vault.read_secret('preferences/ufz-nextcloud/password')}
 ```
 
-This example assumes that the NextCloud username is identical to the Galaxy username. If this is not the case also the username could be a user preference that is stored in a vault.
+This example assumes that the NextCloud username is identical to the Galaxy username. If this is not the case also the username could be a user preference that is stored in a vault.
+
+## Tool Credentials System
+
+Starting with Galaxy 25.1, tools can request credentials directly through a new tool credentials system. This system provides a secure, user-friendly way for tools to access external APIs and services using credentials stored in the vault.
+
+### Overview
+
+The tool credentials system allows tool developers to declaratively specify credential requirements in their tool XML, and Galaxy automatically:
+- Presents a user-friendly credential management interface in the tool form
+- Stores sensitive credentials (secrets) encrypted in the configured vault
+- Injects credentials as environment variables when tools execute
+- Provides centralized credential management in User Preferences
+
+### How it works
+
+1. **Tool Definition**: Tool developers add a `<credentials>` element to their tool XML defining required secrets (API keys, passwords) and optional variables (endpoints, usernames).
+2. **User Experience**: When users run a tool requiring credentials, they see a credential management section in the tool form where they can provide or select existing credentials.
+3. **Secure Storage**: All secrets are automatically stored encrypted in the vault (configured via `vault_config_file`).
+4. **Automatic Injection**: When the tool runs, Galaxy injects the credentials as environment variables into the tool's execution environment.
+
+### Vault Configuration Requirements
+
+The tool credentials system requires a properly configured vault. Any of the supported vault backends (hashicorp, custos, or database) can be used. Ensure you have:
+
+1. Set up your vault configuration as described in the sections above
+2. Configured the `vault_config_file` setting in `galaxy.yml`
+3. Tested that the vault is working properly
+
+The tool credentials system will automatically use the configured vault to store all tool secrets.
+
+### Admin Considerations
+
+- **No additional configuration needed**: Unlike the older user preferences approach, the tool credentials system requires no admin configuration in `user_preferences_extra_conf.yml`. Tools can define their own credential requirements.
+- **Vault is required**: The tool credentials system only works when a vault is configured. If no vault is configured, tools requesting credentials will not function properly.
+- **User isolation**: Each user's credentials are isolated in the vault. Credentials cannot be shared between users.
+- **Migration from user preferences**: If you previously configured tool credentials via `user_preferences_extra_conf.yml`, those can be gradually phased out as tools migrate to the new system. Both systems can coexist.
+
+### API Access
+
+The tool credentials system provides a REST API at `/api/users/{user_id}/credentials` for programmatic credential management. This can be useful for:
+- Automating credential setup for multiple users
+- Building custom credential management interfaces
+- Integrating with external identity management systems
+
+For more information on the tool credentials system from a developer perspective, see the [Tool XML Schema documentation](https://docs.galaxyproject.org/en/master/dev/schema.html#tool-requirements-credentials).