Vault as an access boundary

Folders and CLI toggles are the main safety controls.

Import from files in the app

On macOS, open Vault → Add secrets. Choose Import files for standalone or shared credentials, or Set up a project to import project secrets and configure env files and agent integrations in one review. Manual entry and Adopt SSH keys are also available. The source starts at ~/.zshrc for secrets or ~/.ssh for SSH keys, so you can preview immediately. Edit the path or use Browse to choose another source; Use Default restores the suggested path. Choose a destination folder, preview the proposed changes, select items, choose Password or API Key for each ordinary credential, then confirm Save and Apply Changes. The reference preview updates to match the chosen category. Shell expressions and computed values are skipped. Import files and Set up a project list only values detected as secrets by default; turn on Include all values to list every literal .env and shell assignment, stored as passwords unless detected otherwise. Preview does not write to the vault or source files. Replace originals after saving is checked by default. Clear it to save only, leaving source files, SSH config, and shell integration unchanged. Replacement writes quoted authsia:// exports in shell profiles such as ~/.zshrc and in custom shell files such as ~/.gamesx-env. Sourcing these assignments does not fetch secrets or trigger IDE pairing. Run authsia exec -- npm start to resolve the exported references when needed. Matching CLI-enabled passwords and API keys can be reused on retry. For an existing password, API key, or SSH key in the destination folder, select Overwrite existing value to replace its saved value; this is off by default. The overwrite choice is tied to the reviewed item and included in the single approval. Only one source can be selected to overwrite each existing item. Ambiguous matches and items with CLI access disabled are skipped. Import files groups results by file and offers Select All / Deselect All for the full scan and each file. Set a file environment and override individual secrets, including an explicit Default environment; Use File Environment restores inheritance. Choose Default, All, or one or more named environments, or add a new name. Conflict checks use the chosen environment: Default matches Default, and any shared tag matches, including All. An item tagged All and Production conflicts with both All and Production. If two selected rows from different files would save to the same vault item, the preview warns on both, since a differing value would be skipped. Item IDs, other metadata, and SSH access restrictions are preserved. Imports retain only the latest source-file backup per machine, removing older copies (including a Workspace setup original) after the new snapshot is stored. One vault approval covers the selected items, required backups, and SSH storage verification. Newly scanned secrets and adopted SSH keys have CLI access enabled by default. Conflicts without an overwrite choice are skipped. Scrape backs up and rewrites supported environment and shell files; SSH adoption verifies vault storage before replacing local private keys with Authsia stubs. Changed source files require a new preview.

Keyboard selection

Click an item to focus the Codes or Vault list. Up/Down moves between visible items; Shift+Up/Down extends or shrinks the selection. Command+Up/Down jumps to the first or last item; add Shift to extend the range to that boundary. Selection follows the current sort, search, filters, and expanded folders. Keys typed in text fields stay in the field.

Convert a folder to a workspace

On macOS, right-click a vault folder outside Workspaces and choose Convert to workspace…. Review the destination Workspaces/name, choose a local project, then confirm Move and review setup. Conversion moves all secret types and nested folders together, preserving item IDs, environment tags, and Keychain values. An occupied destination, including one with only child folders, requires a different name; folders are never merged. Projects with existing workspace configuration must be managed through their existing workspace. The local project directory stays in place. Apply the following setup review to create its configuration. If you close setup without applying, choose Move back to return the folder to its original path, or Keep to leave it under Workspaces. Move back is refused, without merging, when something new was saved at the original path. Folder-based references in existing files need the new vault path; conversion does not rewrite project files.

Credential JSON and kubeconfig imports preserve the complete document in a Password item. References for credential-path assignments include ?as=file: authsia exec supplies a private temporary file to the launched command and removes it after the command exits. The source document stays intact. Imports leave unreadable paths and kubeconfigs with external certificate, key, token, or relative authentication-helper dependencies unchanged and explain the issue in the preview. Existing Notes remain usable with file references; no item conversion is required. See credential-file delivery.

Prefer references

Put authsia:// refs in scripts and env files. Secrets resolve only at approved runtime.

SSH via the agent

Git and SSH should sign through Authsia’s agent — not by exporting private keys into the shell. See Secure SSH & Git.

Copy Path stays shell-ready

Copy Path yields export NAME='authsia://…' so pasted refs stay visible to child commands.